@codefast/di 0.10.1 → 0.11.0

package/dist/resolution/resolver.js

@@ -1,19 +1,17 @@
-import { NO_INSTANCE } from "#core/binding";
-import { NO_TAG_KEYS, slotNameCriterionOf } from "#core/tag";
+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 { 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 { AsyncCascadeContext, AsyncLevelContext, buildResolutionFrame, DefaultResolutionContext, } from "#resolution/context";
-import { branchDepthOf, cycleNamesOf, enterResolutionPath, extendResolutionBranch, ROOT_BRANCH, UNOWNED_BRANCH, } from "#resolution/path/resolution-path";
+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, requestedTagKeyMask, selectAllBindings, selectBinding } from "#resolution/select/binding-select";
-// Where a multi-tag resolve switches from scanning the token's list to walking the tag indexes.
-const MULTI_TAG_INDEX_THRESHOLD = 8;
-const EMPTY_STRING_LIST = [];
+import { matchesSlot, selectAllBindings, selectBinding } from "#resolution/select/binding-select";
 const EMPTY_FRAME_LIST = [];
 const EMPTY_PARAM_LIST = [];
 /** Plans compiled so far, with the `null` unplannable marks left out. */
@@ -28,22 +26,15 @@ function countCompiledPlans(plans) {
     }
     return count;
 }
-const ROOT_CONSTRAINT_CONTEXT = {
-    resolutionPath: EMPTY_STRING_LIST,
-    resolutionStack: EMPTY_FRAME_LIST,
-    parent: undefined,
-    ancestors: EMPTY_FRAME_LIST,
-    currentResolveOptions: undefined,
-};
+const ROOT_CONSTRAINT_CONTEXT = new DefaultConstraintContext(EMPTY_FRAME_LIST, undefined);
 /**
  * The resolution engine driving binding selection, instantiation, scoping, and lifecycle hooks.
  *
  * @since 0.3.16-canary.0
  */
 export class DependencyResolver {
-    #syncResolutionContextPool = [];
-    // Contexts bound to the cascade pair — deferred: only an async cascade's sync resolves need it.
-    #cascadeContextPool;
+    // Contexts pooled by depth over the root stack — deferred: a plan-served or constant-only container never needs one.
+    #syncResolutionContextPool;
     /**
      * The stack a top-level **sync** resolve reuses instead of minting an array per call.
      *
@@ -53,25 +44,31 @@ export class DependencyResolver {
      * mints its own. Keeping it stable is also what lets a pooled context skip re-storing it.
      */
     rootStack = [];
-    // The open synchronous factory cascade: its stack is the ancestor chain, and it is balanced
-    // because synchronous code does not interleave.
-    #cascadeStack = [];
-    #cascadeContext;
+    // The last root level's context, kept so one instance is always live: a full collection that finds
+    // none deoptimizes every optimized site that embedded the class's shape, and does so on every
+    // collection after — measured on the async chain rows, and removed by this one field.
+    #recentRootLevelContext;
     // Compiled plans; `null` marks a binding as unplannable under the current cache versions. Both
-    // maps are allocated by the first plan request, which only a class or resolved binding makes.
+    // maps are allocated by the first plan request, which only a class or resolved binding makes. A
+    // root is compiled on the request that repeats it — the first interprets, so a container that
+    // resolves a root once never compiles — and the set below remembers the first.
     #classPlanByBindingId;
+    #classPlanRequestedOnce;
     #classPlanRegistryVersion = -1;
     #classPlanActivationVersion = -1;
     // The async lane's plans, stamped and invalidated apart so neither lane pays the other's misses.
     #asyncPlanByBindingId;
+    #asyncPlanRequestedOnce;
     #asyncPlanRegistryVersion = -1;
     #asyncPlanActivationVersion = -1;
     #registry;
     #scope;
     #lifecycle;
     #metadataReader;
+    #container;
     #parent;
     #lookup;
+    // Built by the first class resolve: a container that never resolves a class never pays for it.
     #classes;
     // Built by the first interpreted resolve that asks; a plan-served or constant-only container never does.
     #activation;
@@ -80,16 +77,19 @@ export class DependencyResolver {
         this.#scope = scope;
         this.#lifecycle = lifecycle;
         this.#metadataReader = metadataReader;
+        this.#container = container;
         this.#parent = parent;
         this.#lookup = new BindingLookupCache(registry, this, parent === undefined ? undefined : parent.#lookup);
-        this.#classes = new ClassIntrospector(metadataReader, container, parent === undefined ? undefined : parent.#classes);
+    }
+    #introspector() {
+        return (this.#classes ??= new ClassIntrospector(this.#metadataReader, this.#container, this.#parent === undefined ? undefined : this.#parent.#introspector()));
     }
     /** The reader this resolver was built with, which is the one its container answers with. */
     get metadataReader() {
         return this.#metadataReader;
     }
     #activationNeed() {
-        return (this.#activation ??= new ActivationNeedCache(this.#lifecycle, this.#classes, this.#registry));
+        return (this.#activation ??= new ActivationNeedCache(this.#lifecycle, this.#introspector(), this.#registry));
     }
     /** Structural counts and the resolver-owned collaborators built so far, for the {@link ResolutionDiagnostics} a container reports. */
     describeCaches() {
@@ -100,18 +100,18 @@ export class DependencyResolver {
         if (this.#lookup.isMemoBuilt) {
             builtSubsystems.push("resolver.lookupMemo");
         }
-        if (this.#activation?.isMemoBuilt === true) {
-            builtSubsystems.push("resolver.activationNeedMemo");
-        }
         const generatedPlanCount = this.#planCompiler?.generatedPlanCount ?? 0;
         if (generatedPlanCount > 0) {
             builtSubsystems.push("resolver.planCodegen");
         }
+        if (this.#recentRootLevelContext !== undefined) {
+            builtSubsystems.push("resolver.asyncRootLevel");
+        }
         return {
             compiledPlanCount: countCompiledPlans(this.#classPlanByBindingId),
             compiledAsyncPlanCount: countCompiledPlans(this.#asyncPlanByBindingId),
             generatedPlanCount,
-            syncContextPoolSize: this.#syncResolutionContextPool.length,
+            syncContextPoolSize: this.#syncResolutionContextPool?.length ?? 0,
             builtSubsystems,
         };
     }
@@ -134,23 +134,19 @@ export class DependencyResolver {
             if (indexed === undefined) {
                 // A one-criterion request matches only a slot carrying exactly that criterion, and every such
                 // slot is in the index, so a miss here is a miss for this registry: nothing left to scan.
-                return this.#parent === undefined
-                    ? undefined
-                    : this.#parent.#findBinding(token, options, resolutionStack, singleCriterion);
+                return this.#forwardingAliasOrParent(token, options, resolutionStack, singleCriterion);
             }
             if (this.#satisfiesPredicate(indexed, options, resolutionStack)) {
                 return { binding: indexed, owner: this };
             }
         }
-        else {
-            if (options.name !== undefined) {
-                const pairTag = loneTagBesideNameOf(options);
-                if (pairTag !== undefined) {
-                    const nameCriterion = slotNameCriterionOf(options.name);
-                    if (nameCriterion === undefined) {
-                        // No binding anywhere has declared this name, so no slot in any registry can carry it.
-                        return undefined;
-                    }
+        else if (options.name !== undefined) {
+            const pairTag = loneTagBesideNameOf(options);
+            if (pairTag !== undefined) {
+                const nameCriterion = slotNameCriterionOf(options.name);
+                // A name interned nowhere cannot key a slot, but a slot whose criteria are a subset of the
+                // request's still matches — so an index miss falls through to the scan, never a clean miss.
+                if (nameCriterion !== undefined) {
                     // The exact two-criterion slot, memoized over the chain; a predicate or an alias declines to the scan.
                     const entry = this.#lookup.namedTaggedEntry(token, nameCriterion, pairTag);
                     if (entry !== null) {
@@ -158,22 +154,6 @@ export class DependencyResolver {
                     }
                 }
             }
-            if (
-            // A threshold switches the data structure, never the semantics: under it the generic scan
-            // below beats walking the indexes, and both paths answer identically. Sized first, so a
-            // small list pays one length read and nothing else.
-            this.#registry.countBindings(token) > MULTI_TAG_INDEX_THRESHOLD &&
-                requestedTagKeyMask(options) !== NO_TAG_KEYS) {
-                // A multi-criterion request matches only slots whose every criterion it carries, and every
-                // such slot is in the two tag indexes — their union is the whole candidate set, unscanned.
-                const selected = this.#selectMultiTagged(token, options, resolutionStack);
-                if (selected !== undefined) {
-                    return { binding: selected, owner: this };
-                }
-                return this.#parent === undefined
-                    ? undefined
-                    : this.#parent.#findBinding(token, options, resolutionStack, singleCriterion);
-            }
         }
         // A lone default-slot candidate is its own selection: the slot match is the whole decision,
         // it carries no predicate, and asking for it first keeps the registry from materialising its list.
@@ -194,10 +174,29 @@ export class DependencyResolver {
                 }
             }
         }
-        if (this.#parent !== undefined) {
-            return this.#parent.#findBinding(token, options, resolutionStack, singleCriterion);
+        if (options === undefined) {
+            return this.#parent === undefined
+                ? undefined
+                : this.#parent.#findBinding(token, options, resolutionStack, singleCriterion);
         }
-        return undefined;
+        return this.#forwardingAliasOrParent(token, options, resolutionStack, singleCriterion);
+    }
+    /**
+     * What a request with criteria finds once no slot of this registry matches them: the token's
+     * default-slot alias, which forwards them to its target, else the parent's answer.
+     *
+     * @remarks A default-slot alias carries no criterion, predicate or membership, so it is a pointer
+     * rather than a candidate — every exact slot here was tried first, and the nearest container that
+     * 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 };
+        }
+        return this.#parent === undefined
+            ? undefined
+            : this.#parent.#findBinding(token, options, resolutionStack, singleCriterion);
     }
     /**
      * The scan a candidate list gets before full selection.
@@ -248,14 +247,40 @@ export class DependencyResolver {
         }
         if (found === undefined) {
             // Thrown here rather than from a helper: the error captures this stack, and an error path is
-            // dominated by that capture. Bindings under the token mean the request matched none of them.
-            if (this.#registry.getAll(currentToken).length > 0) {
-                throw new NoMatchingBindingError(tokenName(currentToken), options ?? {}, this.#registry.availableSlotStrings(currentToken));
+            // 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);
+            if (bound.length > 0) {
+                throw new NoMatchingBindingError(tokenName(currentToken), options ?? {}, bound.map((binding) => bindingSlotToString(binding.slot)));
             }
             throw new TokenNotBoundError(tokenName(currentToken));
         }
         return found;
     }
+    /**
+     * Follows an alias binding's chain to its terminal binding, or `undefined` when the chain ends at
+     * a token nothing matches.
+     *
+     * @remarks The non-throwing twin of {@link DependencyResolver.#requireBinding}'s alias walk, for
+     * the optional and collection lanes: a dangling chain is a miss, but a revisited alias token still
+     * raises {@link CircularDependencyError} — a cycle has no absent reading.
+     */
+    #terminalOfAliasBinding(alias, options, resolutionStack, singleCriterion) {
+        let currentToken = alias.token;
+        let found = { binding: alias, owner: this };
+        let visitedAliasTokens;
+        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, resolutionStack, singleCriterion);
+        }
+        return found;
+    }
     /**
      * Binding lookup aligned with `resolve` — used by `Container.validate` without instantiating.
      */
@@ -346,6 +371,8 @@ export class DependencyResolver {
             if (binding.activationHook !== undefined) {
                 const activationResult = binding.activationHook(resolutionCtx, activated);
                 if (activationResult instanceof Promise) {
+                    // The hook has already run; adopt its rejection so it cannot surface as unhandled.
+                    void activationResult.catch(() => { });
                     throw new AsyncActivationError(tokenDisplayName, "onActivation");
                 }
                 activated = activationResult;
@@ -354,6 +381,7 @@ export class DependencyResolver {
                 for (let index = 0; index < containerHooks.length; index += 1) {
                     const activationResult = containerHooks[index](resolutionCtx, activated);
                     if (activationResult instanceof Promise) {
+                        void activationResult.catch(() => { });
                         throw new AsyncActivationError(tokenDisplayName, "onActivation");
                     }
                     activated = activationResult;
@@ -390,6 +418,7 @@ export class DependencyResolver {
             }
             else {
                 this.#classPlanByBindingId.clear();
+                this.#classPlanRequestedOnce?.clear();
             }
             this.#classPlanRegistryVersion = registryVersion;
             this.#classPlanActivationVersion = activationVersion;
@@ -399,6 +428,12 @@ export class DependencyResolver {
         if (cached !== undefined) {
             return cached;
         }
+        const requestedOnce = (this.#classPlanRequestedOnce ??= new Set());
+        if (!requestedOnce.has(binding.identifier)) {
+            // The first request interprets; the one that repeats it compiles.
+            requestedOnce.add(binding.identifier);
+            return null;
+        }
         const compiled = this.#compiler().compile(binding);
         if (compiled === PLAN_RETRY) {
             // Lifecycle metadata not discovered yet — the fallback resolve discovers it; retry then.
@@ -416,25 +451,24 @@ export class DependencyResolver {
     // The behaviour the plan compiler needs from this resolver — lookups, escapes, plan swaps, and the
     // accessor construction path. Built once with the compiler, so each closure is allocated once.
     #buildPlanCompilerHost() {
+        const classes = this.#introspector();
         return {
             hasActivationHandlers: (binding) => this.#ownerOf(binding).#lifecycle.hasActivationHandlers(binding.token),
-            knownPostConstruct: (target) => this.#classes.knownPostConstruct(target),
-            needsActiveContainer: (target) => this.#classes.needsActiveContainer(target),
+            knownPostConstruct: (target) => classes.knownPostConstruct(target),
+            needsActiveContainer: (target) => classes.needsActiveContainer(target),
             // A plan runs at the top level, so the lent root stack is free when it is; a plan reached
             // with the root stack held mints its own path, exactly as the interpreted lane would.
             constructWithAccessors: (binding, target, deps) => {
                 const stack = this.rootStack.length === 0 ? this.rootStack : [];
-                const frame = this.#getResolutionFrame(binding);
-                const resolutionSet = enterResolutionPath(stack, frame);
+                enterSyncPath(stack, binding, this.#getResolutionFrame(binding));
                 try {
-                    return this.#classes.instantiate(target, deps, this.#ambientResolutionFor(stack));
+                    return classes.instantiate(target, deps, this.#ambientResolutionFor(stack));
                 }
                 finally {
-                    stack.pop();
-                    resolutionSet?.delete(frame.bindingId);
+                    leaveSyncPath(stack, binding);
                 }
             },
-            getConstructorMetadata: (target) => this.#classes.constructorMetadata(target),
+            getConstructorMetadata: (target) => classes.constructorMetadata(target),
             lookupDependencyEntry: (token) => {
                 const entry = this.#lookup.defaultEntry(token);
                 return entry === null ? null : { binding: entry.binding };
@@ -505,6 +539,7 @@ export class DependencyResolver {
             }
             else {
                 this.#asyncPlanByBindingId.clear();
+                this.#asyncPlanRequestedOnce?.clear();
             }
             this.#asyncPlanRegistryVersion = registryVersion;
             this.#asyncPlanActivationVersion = activationVersion;
@@ -514,6 +549,11 @@ export class DependencyResolver {
         if (cached !== undefined) {
             return cached;
         }
+        const requestedOnce = (this.#asyncPlanRequestedOnce ??= new Set());
+        if (!requestedOnce.has(binding.identifier)) {
+            requestedOnce.add(binding.identifier);
+            return null;
+        }
         const compiled = this.#compiler().compileAsync(binding);
         if (compiled === PLAN_RETRY) {
             // Lifecycle metadata not discovered yet — the fallback resolve discovers it; retry then.
@@ -581,7 +621,8 @@ export class DependencyResolver {
         }
         const frame = this.#getResolutionFrame(binding);
         const tokenDisplayName = frame.tokenName;
-        const resolutionSet = enterResolutionPath(resolutionStack, frame);
+        // The level holds its binding's flag for its whole duration, so a factory below runs bare.
+        enterSyncPath(resolutionStack, binding, frame);
         try {
             const needsActivation = owner.#activationNeed().needsActivation(binding);
             if (!needsActivation && scope === "transient" && binding.kind === "dynamic") {
@@ -609,8 +650,7 @@ export class DependencyResolver {
             return activated;
         }
         finally {
-            resolutionStack.pop();
-            resolutionSet?.delete(frame.bindingId);
+            leaveSyncPath(resolutionStack, binding);
         }
     }
     /**
@@ -652,7 +692,9 @@ export class DependencyResolver {
                 throw asyncResolutionErrorFor(binding, resolutionStack);
             case "class": {
                 const deps = this.#resolveDeps(this.#constructorParams(binding.target), resolutionStack);
-                return this.#classes.instantiate(binding.target, deps, this.#classes.needsActiveContainer(binding.target) ? this.#ambientResolutionFor(resolutionStack) : undefined);
+                return this.#introspector().instantiate(binding.target, deps, this.#introspector().needsActiveContainer(binding.target)
+                    ? this.#ambientResolutionFor(resolutionStack)
+                    : undefined);
             }
             case "resolved": {
                 const deps = this.#resolveDeps(binding.deps, resolutionStack);
@@ -675,11 +717,20 @@ export class DependencyResolver {
      * no parameters; anything else is a missing `@injectable()`.
      */
     #constructorParams(target) {
-        const meta = this.#classes.constructorMetadata(target);
+        const meta = this.#introspector().constructorMetadata(target);
         if (meta !== undefined) {
             return meta.params;
         }
         if (target.length === 0) {
+            // A subclass with an implicit constructor and no own metadata inherits its base's declared
+            // deps but would be built with zero arguments, injecting `undefined` silently — reject it.
+            const inherited = this.#introspector().inheritedConstructorMetadata(target);
+            if (inherited !== undefined && inherited.metadata.params.length > 0) {
+                throw new MissingMetadataError(target.name, {
+                    baseName: inherited.base.name,
+                    dependencyCount: inherited.metadata.params.length,
+                });
+            }
             return EMPTY_PARAM_LIST;
         }
         throw new MissingMetadataError(target.name);
@@ -727,16 +778,18 @@ export class DependencyResolver {
                 return undefined;
             }
         }
-        const entry = this.#findBinding(token, options, resolutionStack, precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined));
+        const singleCriterion = precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined);
+        let entry = this.#findBinding(token, options, resolutionStack, singleCriterion);
+        // Resolve the entry the probe found: re-looking the token up would evaluate every `when()`
+        // predicate a second time, and a changed answer would throw where `undefined` was promised.
+        if (entry !== undefined && entry.binding.kind === "alias") {
+            // Follow the alias off the throwing path: a chain that ends nowhere is a miss, not an error.
+            entry = this.#terminalOfAliasBinding(entry.binding, options, resolutionStack, singleCriterion);
+        }
         if (entry === undefined) {
             return undefined;
         }
-        // Resolve the entry the probe found: re-looking the token up would evaluate every `when()`
-        // predicate a second time, and a changed answer would throw where `undefined` was promised.
         const { binding, owner } = entry;
-        if (binding.kind === "alias") {
-            return this.resolve(token, options, resolutionStack);
-        }
         if (binding.scope === "singleton" && owner !== this) {
             return owner.#resolveBinding(binding, options, resolutionStack, owner);
         }
@@ -761,7 +814,10 @@ export class DependencyResolver {
         const resolutionStack = this.rootStack;
         const memo = this.#rootCollection(token, resolutionStack);
         if (memo.values !== undefined && memo.activationVersion === this.#chainActivationVersion()) {
-            return memo.values;
+            // A copy, never the memo itself: a caller that writes into its result must not rewrite the
+            // next caller's. Reading a frozen array is several times slower than reading a plain one, so
+            // the copy is the cheaper guard by far, and it costs one allocation the read already paid before the memo.
+            return memo.values.slice();
         }
         const { candidates } = memo;
         const resolved = new Array(candidates.length);
@@ -778,9 +834,9 @@ export class DependencyResolver {
         const resolutionStack = [];
         const memo = this.#rootCollection(token, resolutionStack);
         if (memo.values !== undefined && memo.activationVersion === this.#chainActivationVersion()) {
-            return Promise.resolve(memo.values);
+            return Promise.resolve(memo.values.slice());
         }
-        return Promise.all(memo.candidates.map((candidate) => this.#resolveCandidateAsync(candidate, undefined, resolutionStack, UNOWNED_BRANCH))).then((values) => {
+        return settleInOrder(memo.candidates.map((candidate) => this.#resolveCandidateAsync(candidate, undefined, resolutionStack, UNOWNED_BRANCH)), (values) => {
             this.#settleCollectionValues(memo);
             return values;
         });
@@ -819,8 +875,7 @@ export class DependencyResolver {
                 return;
             }
         }
-        // Handed out as is, unfrozen: a frozen array iterates through a slow elements kind, so the
-        // contract's read-only return is the guard against a caller writing into the memo.
+        // Kept unfrozen: a frozen array reads through a slow elements kind, and every read copies it anyway.
         entry.values = candidates.map(stableMemberValue);
         entry.activationVersion = 0;
     }
@@ -829,14 +884,37 @@ export class DependencyResolver {
         if (options !== undefined) {
             const indexed = this.#indexedCandidates(token, options, resolutionStack);
             if (indexed !== null) {
-                return indexed;
+                return this.#withoutDanglingAliases(indexed, options, resolutionStack);
             }
         }
         const allBindings = this.#allBindingsFromChain(token);
         if (allBindings.length === 0) {
             return allBindings;
         }
-        return selectAllBindings(allBindings, options, this.#makeConstraintContext(resolutionStack, options));
+        const selected = selectAllBindings(allBindings, options, this.#makeConstraintContext(resolutionStack, options));
+        return this.#withoutDanglingAliases(selected, options, resolutionStack);
+    }
+    /**
+     * The candidates with any alias whose chain ends nowhere dropped, so a fan-out skips a dangling
+     * alias rather than throwing on it.
+     *
+     * @remarks A live alias stays and resolves as before; the common list carries no alias at all and
+     * is returned untouched, so nothing is allocated for it.
+     */
+    #withoutDanglingAliases(candidates, options, resolutionStack) {
+        let hasAlias = false;
+        for (let index = 0; index < candidates.length; index += 1) {
+            if (candidates[index].kind === "alias") {
+                hasAlias = true;
+                break;
+            }
+        }
+        if (!hasAlias) {
+            return candidates;
+        }
+        const singleCriterion = singleCriterionOnlyOf(options);
+        return candidates.filter((candidate) => candidate.kind !== "alias" ||
+            this.#terminalOfAliasBinding(candidate, options, resolutionStack, singleCriterion) !== undefined);
     }
     // ── Async resolve ──────────────────────────────────────────────────────────────────────────────────────────────────
     resolveAsyncFromContext(token, resolutionStack, branchDepth) {
@@ -898,11 +976,13 @@ export class DependencyResolver {
         return this.#resolveBindingAsync(binding, options, [], ROOT_BRANCH, this);
     }
     async resolveAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH, precomputedCriterion) {
-        const { binding, owner } = this.#requireBinding(token, options, resolutionStack, 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, resolutionStack, branchDepth, owner);
+            return owner.#resolveBindingAsync(binding, options, path, depth, owner);
         }
-        return this.#resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner);
+        return this.#resolveBindingAsync(binding, options, path, depth, owner);
     }
     async #resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner) {
         if (owner.#isPlainConstant(binding)) {
@@ -943,15 +1023,18 @@ export class DependencyResolver {
         const needsActivation = owner.#activationNeed().needsActivation(binding);
         if (!needsActivation && scope === "transient" && (binding.kind === "dynamic" || binding.kind === "dynamic-async")) {
             const resolutionCtx = new AsyncLevelContext(this, levelStack, options);
-            if (binding.kind === "dynamic-async") {
-                return await binding.factory(resolutionCtx);
+            if (branchDepth === ROOT_BRANCH) {
+                this.#recentRootLevelContext = resolutionCtx;
             }
-            const dynamicResult = binding.factory(resolutionCtx);
+            const dynamicResult = runFactoryPrefix(binding, resolutionCtx, levelStack);
             return dynamicResult instanceof Promise ? await dynamicResult : dynamicResult;
         }
         const resolutionCtx = needsActivation || requiresResolutionContext(binding)
             ? new AsyncLevelContext(this, levelStack, options)
             : undefined;
+        if (resolutionCtx !== undefined && branchDepth === ROOT_BRANCH) {
+            this.#recentRootLevelContext = resolutionCtx;
+        }
         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) => {
@@ -988,8 +1071,10 @@ export class DependencyResolver {
      * this binding on every call, forever.
      */
     #mirrorPostConstructFromOwner(binding, owner) {
-        if (owner !== this && binding.kind === "class" && this.#classes.knownPostConstruct(binding.target) === undefined) {
-            this.#classes.discoverPostConstruct(binding.target);
+        if (owner !== this &&
+            binding.kind === "class" &&
+            this.#introspector().knownPostConstruct(binding.target) === undefined) {
+            this.#introspector().discoverPostConstruct(binding.target);
         }
     }
     async #instantiateAndActivateAsync(binding, ctx, resolutionStack, branchDepth, needsActivation, owner) {
@@ -1004,22 +1089,20 @@ export class DependencyResolver {
         switch (binding.kind) {
             case "constant":
                 return binding.value;
-            case "dynamic": {
+            case "dynamic":
+            case "dynamic-async": {
                 if (ctx === undefined) {
                     throw new InternalError("dynamic binding requires resolution context");
                 }
-                const factoryResult = binding.factory(ctx);
+                const factoryResult = runFactoryPrefix(binding, ctx, resolutionStack);
                 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.#resolveDepsAsync(this.#constructorParams(binding.target), resolutionStack, branchDepth);
                 // Accessor initializers resolve synchronously, so the branch-owned path serves them directly.
-                return this.#classes.instantiate(binding.target, deps, this.#classes.needsActiveContainer(binding.target) ? this.#ambientResolutionFor(resolutionStack) : undefined);
+                return this.#introspector().instantiate(binding.target, deps, this.#introspector().needsActiveContainer(binding.target)
+                    ? this.#ambientResolutionFor(resolutionStack)
+                    : undefined);
             }
             case "resolved": {
                 const deps = await this.#resolveDepsAsync(binding.deps, resolutionStack, branchDepth);
@@ -1048,7 +1131,7 @@ export class DependencyResolver {
         for (let index = 0; index < count; index += 1) {
             pending[index] = this.#resolveDepAsync(deps[index], resolutionStack, branchDepth);
         }
-        return Promise.all(pending);
+        return settleInOrder(pending, identity);
     }
     #resolveDepAsync(dep, resolutionStack, branchDepth) {
         const options = resolveOptionsForSlot(dep);
@@ -1064,27 +1147,33 @@ export class DependencyResolver {
         return this.resolveAsync(dep.token, options, resolutionStack, branchDepth, singleCriterionForSlot(dep));
     }
     async resolveOptionalAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH, precomputedCriterion) {
-        const entry = this.#findBinding(token, options, resolutionStack, precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined));
+        const path = ownPrefixOf(resolutionStack, branchDepth);
+        const depth = path === resolutionStack ? branchDepth : branchDepthOf(path);
+        const singleCriterion = precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined);
+        let entry = this.#findBinding(token, options, path, singleCriterion);
+        // Same single-evaluation contract as the sync lane: resolve what the probe found.
+        if (entry !== undefined && entry.binding.kind === "alias") {
+            // Follow the alias off the throwing path: a chain that ends nowhere is a miss, not an error.
+            entry = this.#terminalOfAliasBinding(entry.binding, options, path, singleCriterion);
+        }
         if (entry === undefined) {
             return undefined;
         }
-        // Same single-evaluation contract as the sync lane: resolve what the probe found.
         const { binding, owner } = entry;
-        if (binding.kind === "alias") {
-            return this.resolveAsync(token, options, resolutionStack, branchDepth);
-        }
         if (binding.scope === "singleton" && owner !== this) {
-            return owner.#resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner);
+            return owner.#resolveBindingAsync(binding, options, path, depth, owner);
         }
-        return this.#resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner);
+        return this.#resolveBindingAsync(binding, options, path, depth, owner);
     }
     async resolveAllAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH) {
-        const candidates = this.#candidateBindings(token, options, resolutionStack);
+        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, resolutionStack, branchDepth);
+            pending[index] = this.#resolveCandidateAsync(candidates[index], options, path, depth);
         }
-        return Promise.all(pending);
+        return settleInOrder(pending, identity);
     }
     // ── Helpers ────────────────────────────────────────────────────────────────────────────────────────────────────────
     #allBindingsFromChain(token) {
@@ -1173,46 +1262,7 @@ export class DependencyResolver {
         if (options === undefined && resolutionStack.length === 0) {
             return ROOT_CONSTRAINT_CONTEXT;
         }
-        return buildConstraintContext(resolutionStack, options);
-    }
-    /** Selection for a multi-criterion request, over the union of the two tag indexes. */
-    #selectMultiTagged(token, options, resolutionStack) {
-        const candidates = [];
-        const gathered = [];
-        if (options.name !== undefined) {
-            // Read, not minted: an unminted name has no criterion, so no slot can carry it.
-            this.#gatherTagCandidates(token, slotNameCriterionOf(options.name), candidates, gathered);
-        }
-        this.#gatherTagCandidates(token, options.tag, candidates, gathered);
-        const listed = options.tags;
-        if (listed !== undefined) {
-            for (let index = 0; index < listed.length; index += 1) {
-                this.#gatherTagCandidates(token, listed[index], candidates, gathered);
-            }
-        }
-        if (candidates.length === 0) {
-            return undefined;
-        }
-        return selectBinding(candidates, options, this.#makeConstraintContext(resolutionStack, options), tokenName(token));
-    }
-    /** One request criterion's candidates: its exact single-tag binding, plus its first-tag bucket. */
-    #gatherTagCandidates(token, criterion, out, gathered) {
-        // Distinct criteria never share a binding — a slot lives in exactly one bucket — so deduping
-        // by criterion covers a request repeating one across its spellings, without scanning `out`.
-        if (criterion === undefined || gathered.includes(criterion)) {
-            return;
-        }
-        gathered.push(criterion);
-        const single = this.#registry.getSimpleTagged(token, criterion);
-        if (single !== undefined) {
-            out.push(single);
-        }
-        const bucket = this.#registry.getMultiTagged(token, criterion);
-        if (bucket !== undefined) {
-            for (let index = 0; index < bucket.length; index += 1) {
-                out.push(bucket[index]);
-            }
-        }
+        return new DefaultConstraintContext(resolutionStack, options);
     }
     /** The predicate half of a match, for a lane whose index has already settled the slot. */
     #satisfiesPredicate(binding, options, resolutionStack) {
@@ -1257,68 +1307,64 @@ export class DependencyResolver {
         }
         // 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;
+        }
         try {
-            if (binding.kind === "dynamic-async") {
-                return binding.factory(ctx);
-            }
-            const factoryResult = binding.factory(ctx);
+            const factoryResult = runFactoryPrefix(binding, ctx, levelStack);
             return factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
         }
         catch (factoryError) {
             return Promise.reject(factoryError);
         }
     }
-    // ── The cascade lane ───────────────────────────────────────────────────────────────────────────────────────────────
+    // ── The async root ─────────────────────────────────────────────────────────────────────────────────────────────────
     /**
-     * Entry for a request a factory makes from inside an open synchronous cascade.
+     * Entry for an options-less resolve the container starts: the root of a branch of its own.
      *
-     * @remarks A request arriving with no cascade open came out of a continuation, so its ancestors
-     * are on no call stack — it escapes to the branch lane.
+     * @remarks A statically-visible transient graph answers from its compiled async plan; everything
+     * else opens a branch over a fresh array, so every level's context keeps its own ancestors for as
+     * long as the factory holds it — across an `await` included.
      */
-    resolveAsyncFromCascade(token) {
-        if (this.#cascadeStack.length === 0) {
-            return this.resolveAsyncFromContext(token, [], ROOT_BRANCH);
-        }
-        return this.#dispatchCascade(token);
-    }
-    /** Entry for a resolve the container starts, which opens the cascade rather than joining one. */
     resolveAsyncFromRoot(token) {
-        return this.#dispatchCascade(token);
-    }
-    #dispatchCascade(token) {
         const fastBinding = this.#registry.getFastDefault(token);
         if (fastBinding !== undefined) {
-            if ((fastBinding.kind === "dynamic-async" || fastBinding.kind === "dynamic") &&
-                fastBinding.scope === "transient" &&
-                !this.#hasAnyActivation(fastBinding)) {
-                return this.#resolveTransientDynamicAsyncCascade(fastBinding);
-            }
-            // A value that already exists answers here: escaping would snapshot the cascade for a resolve
-            // that never looks at a path.
-            if (this.#isPlainConstant(fastBinding)) {
-                return Promise.resolve(fastBinding.value);
-            }
-            if (fastBinding.scope === "singleton" && fastBinding.instance !== NO_INSTANCE) {
-                return Promise.resolve(fastBinding.instance);
-            }
-            const planned = this.#plannedCascadeAnswer(fastBinding);
+            const planned = this.#plannedRootAnswer(fastBinding);
             if (planned !== null) {
                 return planned;
             }
+            if (fastBinding.scope === "transient" &&
+                (fastBinding.kind === "dynamic" || fastBinding.kind === "dynamic-async") &&
+                !this.#hasAnyActivation(fastBinding)) {
+                return this.#rootFactoryAnswer(fastBinding);
+            }
         }
-        // Anything else leaves the cascade lane for good, seeded with a snapshot of the ancestors it
-        // accumulated — so a cycle across the boundary is still on one path.
-        return this.resolveAsyncFromContext(token, [...this.#cascadeStack], UNOWNED_BRANCH);
+        return this.resolveAsyncFromContext(token, [], ROOT_BRANCH);
     }
     /**
-     * A statically-visible transient graph at a true root answers from its compiled async plan.
+     * A transient factory root's answer: its factory run over the one context the binding keeps.
      *
-     * @remarks Kept out of the dispatcher so its size stays inlinable. Inside an open cascade the
-     * graph must escape instead, so its escapes carry the live ancestors — hence the idle gate.
+     * @remarks The root's path is its own frame alone and the request carries no options, so the level's
+     * context is a function of the binding, built on the first resolve and reused by every later one —
+     * a concurrent root reads the same path, and a descendant that outgrows the branch copies its prefix.
      */
-    #plannedCascadeAnswer(fastBinding) {
-        if (this.#cascadeStack.length !== 0 ||
-            fastBinding.scope !== "transient" ||
+    #rootFactoryAnswer(binding) {
+        let ctx = binding.rootContext;
+        if (ctx === undefined) {
+            ctx = new AsyncLevelContext(this, extendResolutionBranch([], ROOT_BRANCH, this.#getResolutionFrame(binding)), undefined);
+            binding.rootContext = ctx;
+        }
+        try {
+            const factoryResult = runFactoryPrefix(binding, ctx, ctx.ownPath);
+            return factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
+        }
+        catch (factoryError) {
+            return Promise.reject(factoryError);
+        }
+    }
+    /** The compiled async plan's answer for a transient class or factory root, or `null` when there is none. */
+    #plannedRootAnswer(fastBinding) {
+        if (fastBinding.scope !== "transient" ||
             (fastBinding.kind !== "class" && fastBinding.kind !== "resolved" && fastBinding.kind !== "resolved-async")) {
             return null;
         }
@@ -1335,32 +1381,6 @@ export class DependencyResolver {
             return Promise.reject(planError);
         }
     }
-    #resolveTransientDynamicAsyncCascade(binding) {
-        const frame = this.#getResolutionFrame(binding);
-        // The request that closes a cycle is made from a factory's synchronous prefix, and synchronous
-        // code does not interleave — so the O(1) flag is exact path membership here, as it is for the
-        // sync lane. It is cleared when the factory returns its promise, not when that promise settles.
-        if (binding.inFlight) {
-            return Promise.reject(new CircularDependencyError(cycleNamesOf(this.#cascadeStack, frame.tokenName)));
-        }
-        const ctx = (this.#cascadeContext ??= new AsyncCascadeContext(this, this.#cascadeStack));
-        binding.inFlight = true;
-        this.#cascadeStack.push(frame);
-        try {
-            if (binding.kind === "dynamic-async") {
-                return binding.factory(ctx);
-            }
-            const factoryResult = binding.factory(ctx);
-            return factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
-        }
-        catch (factoryError) {
-            return Promise.reject(factoryError);
-        }
-        finally {
-            this.#cascadeStack.pop();
-            binding.inFlight = false;
-        }
-    }
     // A cached candidate answers here rather than re-entering the generic path: `resolveAll` pays
     // this per candidate, and a fan-out over cached handlers is the shape that makes it matter.
     #resolveCandidateSync(binding, options, resolutionStack) {
@@ -1434,7 +1454,7 @@ export class DependencyResolver {
         if (existing !== undefined) {
             return existing;
         }
-        const frame = buildResolutionFrame(tokenName(binding.token), binding.scope, binding.identifier, binding.kind, binding.slot);
+        const frame = buildResolutionFrame(binding, tokenName(binding.token));
         binding.frame = frame;
         return frame;
     }
@@ -1444,32 +1464,18 @@ export class DependencyResolver {
     #acquireSyncResolutionContext(resolutionStack, options) {
         if (resolutionStack === this.rootStack) {
             const depth = resolutionStack.length;
-            const existing = this.#syncResolutionContextPool[depth];
+            const pool = (this.#syncResolutionContextPool ??= []);
+            const existing = pool[depth];
             if (existing !== undefined) {
                 existing.reset(this, resolutionStack, options);
                 return existing;
             }
             const created = new DefaultResolutionContext(this, resolutionStack, options);
-            this.#syncResolutionContextPool[depth] = created;
+            pool[depth] = created;
             return created;
         }
-        return this.#acquireOffRootSyncContext(resolutionStack, options);
-    }
-    /** The cascade pair pools separately; a throwaway pair (nested resolve, async snapshot) mints per call. */
-    #acquireOffRootSyncContext(resolutionStack, options) {
-        if (resolutionStack !== this.#cascadeStack) {
-            return new DefaultResolutionContext(this, resolutionStack, options);
-        }
-        const depth = resolutionStack.length;
-        const pool = (this.#cascadeContextPool ??= []);
-        const existing = pool[depth];
-        if (existing !== undefined) {
-            existing.reset(this, resolutionStack, options);
-            return existing;
-        }
-        const created = new DefaultResolutionContext(this, resolutionStack, options);
-        pool[depth] = created;
-        return created;
+        // A throwaway pair — a nested resolve, an async level's prefix — mints per call.
+        return new DefaultResolutionContext(this, resolutionStack, options);
     }
 }
 /**
@@ -1496,27 +1502,51 @@ function anyPredicate(bindings) {
     }
     return false;
 }
-function buildConstraintContext(resolutionStack, options) {
-    return {
-        // Derived per read, never cached: the stack may be live, and the names must report it as it stands.
-        get resolutionPath() {
-            const names = new Array(resolutionStack.length);
-            for (let index = 0; index < resolutionStack.length; index += 1) {
-                names[index] = resolutionStack[index].tokenName;
-            }
-            return names;
-        },
-        resolutionStack,
-        parent: resolutionStack.at(-1),
-        ancestors: resolutionStack.length > 1 ? resolutionStack.slice(0, -1) : [],
-        currentResolveOptions: options,
-    };
+/**
+ * Runs an async lane's factory with its binding flagged in flight for the factory's synchronous prefix.
+ *
+ * @remarks The flag is exact path membership only while synchronous code runs, so it is cleared when
+ * the factory returns — its promise included — never when that promise settles: two branches that
+ * await one binding are a diamond, not a cycle. A factory that resolves its own token from that
+ * prefix is caught before it runs again, on the branch lane as on the sync lanes, where the level's
+ * own flag already covers the whole call.
+ */
+function runFactoryPrefix(binding, ctx, levelStack) {
+    if (binding.inFlight) {
+        // The level's own frame is the last one, and the path an error names ends where the cycle closed.
+        throw new CircularDependencyError(cycleNamesOf(levelStack.slice(0, -1), tokenName(binding.token)));
+    }
+    binding.inFlight = true;
+    try {
+        return binding.factory(ctx);
+    }
+    finally {
+        binding.inFlight = false;
+    }
+}
+/**
+ * The frames a level may read as its own path: the array itself while nothing has grown it past the
+ * level's depth, else a copy of the level's prefix.
+ *
+ * @remarks Siblings start concurrently on one branch and the first appends in place, so a later
+ * sibling that read the whole array would hand a `when()` predicate the first sibling's frame as its
+ * parent. The copy is the one the branch lane would take for that sibling anyway, and it owns itself.
+ */
+function ownPrefixOf(resolutionStack, branchDepth) {
+    if (branchDepth === UNOWNED_BRANCH || resolutionStack.length === branchDepth) {
+        return resolutionStack;
+    }
+    return resolutionStack.slice(0, branchDepth);
 }
 /** The async-resolution failure for a binding reached on a sync path, naming what to await instead. */
 function asyncResolutionErrorFor(binding, resolutionStack) {
     const sourceName = tokenName(binding.token);
     return new AsyncResolutionError(resolutionStack[0]?.tokenName ?? sourceName, sourceName);
 }
+/** The settled values of a fan-out, as they are. */
+function identity(values) {
+    return values;
+}
 /** 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";