@codefast/di 0.8.1 → 0.10.0

package/dist/resolution/resolver.js

@@ -2,7 +2,7 @@ import { NO_INSTANCE } from "#/core/binding";
 import { NO_TAG_KEYS, slotNameCriterionOf } from "#/core/tag";
 import { tokenName } from "#/core/token";
 import { AsyncActivationError, AsyncResolutionError, CircularDependencyError, DisposedContainerError, InternalError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, TokenNotBoundError, } from "#/errors/errors";
-import { resolveOptionsForSlot, singleCriterionForSlot, singleCriterionOnlyOf } from "#/injection/resolve-options";
+import { loneTagBesideNameOf, resolveOptionsForSlot, singleCriterionForSlot, singleCriterionOnlyOf, } from "#/injection/resolve-options";
 import { SCOPED_MISS } from "#/lifecycle/scope-manager";
 import { ActivationNeedCache } from "#/resolution/cache/activation-need";
 import { BindingLookupCache } from "#/resolution/cache/binding-lookup-cache";
@@ -16,6 +16,18 @@ const MULTI_TAG_INDEX_THRESHOLD = 8;
 const EMPTY_STRING_LIST = [];
 const EMPTY_FRAME_LIST = [];
 const EMPTY_PARAM_LIST = [];
+/** Plans compiled so far, with the `null` unplannable marks left out. */
+function countCompiledPlans(plans) {
+    let count = 0;
+    if (plans !== undefined) {
+        for (const plan of plans.values()) {
+            if (plan !== null) {
+                count += 1;
+            }
+        }
+    }
+    return count;
+}
 const ROOT_CONSTRAINT_CONTEXT = {
     resolutionPath: EMPTY_STRING_LIST,
     resolutionStack: EMPTY_FRAME_LIST,
@@ -45,12 +57,13 @@ export class DependencyResolver {
     // because synchronous code does not interleave.
     #cascadeStack = [];
     #cascadeContext;
-    // Compiled plans; `null` marks a binding as unplannable under the current cache versions.
-    #classPlanByBindingId = new Map();
+    // 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.
+    #classPlanByBindingId;
     #classPlanRegistryVersion = -1;
     #classPlanActivationVersion = -1;
     // The async lane's plans, stamped and invalidated apart so neither lane pays the other's misses.
-    #asyncPlanByBindingId = new Map();
+    #asyncPlanByBindingId;
     #asyncPlanRegistryVersion = -1;
     #asyncPlanActivationVersion = -1;
     #registry;
@@ -60,6 +73,7 @@ export class DependencyResolver {
     #parent;
     #lookup;
     #classes;
+    // Built by the first interpreted resolve that asks; a plan-served or constant-only container never does.
     #activation;
     constructor(registry, scope, lifecycle, metadataReader, container, parent) {
         this.#registry = registry;
@@ -68,31 +82,37 @@ export class DependencyResolver {
         this.#metadataReader = metadataReader;
         this.#parent = parent;
         this.#lookup = new BindingLookupCache(registry, this, parent === undefined ? undefined : parent.#lookup);
-        this.#classes = new ClassIntrospector(metadataReader, container);
-        this.#activation = new ActivationNeedCache(lifecycle, this.#classes, registry);
+        this.#classes = new ClassIntrospector(metadataReader, container, parent === undefined ? undefined : parent.#classes);
     }
     /** The reader this resolver was built with, which is the one its container answers with. */
     get metadataReader() {
         return this.#metadataReader;
     }
-    /** Structural counts for the {@link ResolutionDiagnostics} a container reports. */
+    #activationNeed() {
+        return (this.#activation ??= new ActivationNeedCache(this.#lifecycle, this.#classes, this.#registry));
+    }
+    /** Structural counts and the resolver-owned collaborators built so far, for the {@link ResolutionDiagnostics} a container reports. */
     describeCaches() {
-        let compiledPlanCount = 0;
-        for (const plan of this.#classPlanByBindingId.values()) {
-            if (plan !== null) {
-                compiledPlanCount += 1;
-            }
+        const builtSubsystems = [];
+        if (this.#planCompiler !== undefined) {
+            builtSubsystems.push("resolver.planCompiler");
         }
-        let compiledAsyncPlanCount = 0;
-        for (const plan of this.#asyncPlanByBindingId.values()) {
-            if (plan !== null) {
-                compiledAsyncPlanCount += 1;
-            }
+        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");
         }
         return {
-            compiledPlanCount,
-            compiledAsyncPlanCount,
+            compiledPlanCount: countCompiledPlans(this.#classPlanByBindingId),
+            compiledAsyncPlanCount: countCompiledPlans(this.#asyncPlanByBindingId),
+            generatedPlanCount,
             syncContextPoolSize: this.#syncResolutionContextPool.length,
+            builtSubsystems,
         };
     }
     // ── Binding lookup ─────────────────────────────────────────────────────────────────────────────────────────────────
@@ -111,37 +131,67 @@ export class DependencyResolver {
         }
         else if (singleCriterion !== undefined) {
             const indexed = this.#registry.getSimpleTagged(token, singleCriterion);
-            if (indexed !== undefined && this.#satisfiesPredicate(indexed, options, resolutionStack)) {
+            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);
+            }
+            if (this.#satisfiesPredicate(indexed, options, resolutionStack)) {
                 return { binding: indexed, owner: this };
             }
         }
-        else 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.getAll(token).length > 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);
-        }
-        const bindings = this.#registry.getAll(token);
-        if (bindings.length > 0) {
-            // A lone candidate is its own selection: matching it is the whole decision, with no
-            // specificity to weigh and no ambiguity to report.
-            const selected = bindings.length === 1
-                ? matchesSlot(bindings[0].slot, options) && this.#satisfiesPredicate(bindings[0], options, resolutionStack)
-                    ? bindings[0]
-                    : undefined
-                : selectBinding(bindings, options, this.#makeConstraintContext(resolutionStack, options), tokenName(token));
-            if (selected !== undefined) {
-                return { binding: selected, 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;
+                    }
+                    // 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) {
+                        return entry;
+                    }
+                }
+            }
+            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.
+        // An options-less request already probed the lone map above, so only a request with options asks again.
+        const lone = options === undefined ? undefined : this.#registry.getFastDefault(token);
+        if (lone !== undefined) {
+            if (matchesSlot(lone.slot, options)) {
+                return { binding: lone, owner: this };
+            }
+        }
+        else {
+            // The lone map has missed either way, so the record map is all that is left to read.
+            const bindings = this.#registry.getRecorded(token);
+            if (bindings.length > 0) {
+                const selected = this.#selectFromList(bindings, options, resolutionStack, token);
+                if (selected !== undefined) {
+                    return { binding: selected, owner: this };
+                }
             }
         }
         if (this.#parent !== undefined) {
@@ -149,6 +199,31 @@ export class DependencyResolver {
         }
         return undefined;
     }
+    /**
+     * The scan a candidate list gets before full selection.
+     *
+     * @remarks A single slot match is the whole answer once its predicate, if any, agrees, and no
+     * match is a clean miss; neither needs a display name or a candidate array. Two slot matches
+     * hand the same list to full selection, which weighs specificity and reports ambiguity — so both
+     * lanes answer identically.
+     */
+    #selectFromList(bindings, options, resolutionStack, token) {
+        let match;
+        for (let index = 0; index < bindings.length; index += 1) {
+            const candidate = bindings[index];
+            if (candidate.isMany || !matchesSlot(candidate.slot, options)) {
+                continue;
+            }
+            if (match !== undefined) {
+                return selectBinding(bindings, options, this.#makeConstraintContext(resolutionStack, options), tokenName(token));
+            }
+            match = candidate;
+        }
+        if (match === undefined) {
+            return undefined;
+        }
+        return this.#satisfiesPredicate(match, options, resolutionStack) ? match : undefined;
+    }
     /**
      * The binding a token resolves to with alias hops followed, or a diagnostic throw.
      *
@@ -214,7 +289,7 @@ export class DependencyResolver {
                 // Container-level hooks belong to the binding's owner — a child-registered hook must not
                 // fire for a parent-owned binding, and the owner's must.
                 const containerHooks = owner.#lifecycle.activationVersion === 0 ? undefined : owner.#lifecycle.activationHandlersFor(binding.token);
-                if (binding.onActivation === undefined && (containerHooks === undefined || containerHooks.length === 0)) {
+                if (binding.activationHook === undefined && (containerHooks === undefined || containerHooks.length === 0)) {
                     return this.#resolveTransientDynamicSyncFromContext(binding, resolutionStack);
                 }
                 return this.#resolveTransientDynamicActivatedSync(binding, containerHooks, resolutionStack);
@@ -268,8 +343,8 @@ export class DependencyResolver {
                 throw new AsyncResolutionError(resolutionStack[0]?.tokenName ?? tokenDisplayName, tokenDisplayName);
             }
             let activated = factoryResult;
-            if (binding.onActivation !== undefined) {
-                const activationResult = binding.onActivation(resolutionCtx, activated);
+            if (binding.activationHook !== undefined) {
+                const activationResult = binding.activationHook(resolutionCtx, activated);
                 if (activationResult instanceof Promise) {
                     throw new AsyncActivationError(tokenDisplayName, "onActivation");
                 }
@@ -291,8 +366,14 @@ export class DependencyResolver {
             binding.inFlight = false;
         }
     }
-    /** Chain-summed activation version: a plan can inline a parent-owned binding, so a parent's hook registration must invalidate it. */
+    /**
+     * Chain-summed activation version: a plan can inline a parent-owned binding, so a parent's hook
+     * registration must invalidate it.
+     */
     #chainActivationVersion() {
+        if (this.#parent === undefined) {
+            return this.#lifecycle.activationVersion;
+        }
         let version = this.#lifecycle.activationVersion;
         for (let current = this.#parent; current !== undefined; current = current.#parent) {
             version += current.#lifecycle.activationVersion;
@@ -303,93 +384,137 @@ export class DependencyResolver {
         const registryVersion = this.#lookup.chainVersion();
         const activationVersion = this.#chainActivationVersion();
         if (registryVersion !== this.#classPlanRegistryVersion || activationVersion !== this.#classPlanActivationVersion) {
-            this.#classPlanByBindingId.clear();
+            // The stamps start at -1, so the first request always lands here: allocate then, clear after.
+            if (this.#classPlanByBindingId === undefined) {
+                this.#classPlanByBindingId = new Map();
+            }
+            else {
+                this.#classPlanByBindingId.clear();
+            }
             this.#classPlanRegistryVersion = registryVersion;
             this.#classPlanActivationVersion = activationVersion;
         }
-        const cached = this.#classPlanByBindingId.get(binding.id);
+        const plans = this.#classPlanByBindingId;
+        const cached = plans.get(binding.identifier);
         if (cached !== undefined) {
             return cached;
         }
-        const compiled = this.#planCompiler.compile(binding);
+        const compiled = this.#compiler().compile(binding);
         if (compiled === PLAN_RETRY) {
             // Lifecycle metadata not discovered yet — the fallback resolve discovers it; retry then.
             return null;
         }
-        this.#classPlanByBindingId.set(binding.id, compiled);
+        plans.set(binding.identifier, compiled);
         return compiled;
     }
-    // Compiler behind #getInstantiationPlan — cold path, so the host indirection costs nothing hot.
-    #planCompiler = new InstantiationPlanCompiler({
-        hasActivationHandlers: (binding) => this.#ownerOf(binding).#lifecycle.hasActivationHandlers(binding.token),
-        knownPostConstruct: (target) => this.#classes.knownPostConstruct(target),
-        needsActiveContainer: (target) => this.#classes.needsActiveContainer(target),
-        getConstructorMetadata: (target) => this.#classes.constructorMetadata(target),
-        lookupDependencyEntry: (token) => {
-            const entry = this.#lookup.defaultEntry(token);
-            return entry === null ? null : { binding: entry.binding };
-        },
-        // Exactly what #findBinding's single-criterion lane accepts, minus the half that reads a path:
-        // a predicate is the compiler's cue to leave the selection to the runtime.
-        lookupPathIndependentEntry: (token, options) => {
-            const singleCriterion = singleCriterionOnlyOf(options);
-            if (singleCriterion === undefined) {
-                return null;
-            }
-            const entry = this.#lookup.taggedEntry(token, singleCriterion);
-            if (entry === null || entry.binding.predicate !== undefined || !matchesSlot(entry.binding.slot, options)) {
-                return null;
-            }
-            return { binding: entry.binding };
-        },
-        getResolutionFrame: (binding) => this.#getResolutionFrame(binding),
-        // Dispatches exactly as #resolveDep does, so an escaped dep is indistinguishable
-        // from the same dep on a fully interpreted resolve.
-        resolveEscaped: (token, options, arity, resolutionStack) => {
-            if (arity === "all") {
-                return this.resolveAll(token, options, resolutionStack);
-            }
-            if (arity === "optional") {
-                return this.resolveOptional(token, options, resolutionStack);
-            }
-            if (options === undefined) {
-                return this.resolveFromContext(token, resolutionStack);
-            }
-            return this.resolve(token, options, resolutionStack);
-        },
-        // Dispatches exactly as #resolveDepAsync does, for the async lane's escapes.
-        resolveEscapedAsync: (token, options, arity, resolutionStack) => {
-            if (arity === "all") {
-                return this.resolveAllAsync(token, options, resolutionStack, UNOWNED_BRANCH);
-            }
-            if (arity === "optional") {
-                return this.resolveOptionalAsync(token, options, resolutionStack, UNOWNED_BRANCH);
-            }
-            if (options === undefined) {
-                return this.resolveAsyncFromContext(token, resolutionStack, UNOWNED_BRANCH);
-            }
-            return this.resolveAsync(token, options, resolutionStack, UNOWNED_BRANCH);
-        },
-    });
+    // Compiler behind #getInstantiationPlan — a cold path, and built on the first plan so a container
+    // that never resolves a class or a resolved factory never pays for the host.
+    #planCompiler;
+    #compiler() {
+        return (this.#planCompiler ??= new InstantiationPlanCompiler({
+            hasActivationHandlers: (binding) => this.#ownerOf(binding).#lifecycle.hasActivationHandlers(binding.token),
+            knownPostConstruct: (target) => this.#classes.knownPostConstruct(target),
+            needsActiveContainer: (target) => this.#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);
+                try {
+                    return this.#classes.instantiate(target, deps, this.#ambientResolutionFor(stack));
+                }
+                finally {
+                    stack.pop();
+                    resolutionSet?.delete(frame.bindingId);
+                }
+            },
+            getConstructorMetadata: (target) => this.#classes.constructorMetadata(target),
+            lookupDependencyEntry: (token) => {
+                const entry = this.#lookup.defaultEntry(token);
+                return entry === null ? null : { binding: entry.binding };
+            },
+            // Exactly what #findBinding's single-criterion lane accepts, minus the half that reads a path:
+            // a predicate is the compiler's cue to leave the selection to the runtime.
+            lookupPathIndependentEntry: (token, options) => {
+                const singleCriterion = singleCriterionOnlyOf(options);
+                if (singleCriterion === undefined) {
+                    return null;
+                }
+                const entry = this.#lookup.taggedEntry(token, singleCriterion);
+                if (entry === null || entry.binding.predicate !== undefined || !matchesSlot(entry.binding.slot, options)) {
+                    return null;
+                }
+                return { binding: entry.binding };
+            },
+            getResolutionFrame: (binding) => this.#getResolutionFrame(binding),
+            // Identity-guarded: a map cleared and recompiled since no longer holds the plan being replaced.
+            replacePlan: (binding, current, next) => {
+                const plans = this.#classPlanByBindingId;
+                if (plans !== undefined && plans.get(binding.identifier) === current) {
+                    plans.set(binding.identifier, next);
+                }
+            },
+            replaceAsyncPlan: (binding, current, next) => {
+                const plans = this.#asyncPlanByBindingId;
+                if (plans !== undefined && plans.get(binding.identifier) === current) {
+                    plans.set(binding.identifier, next);
+                }
+            },
+            // Dispatches exactly as #resolveDep does, so an escaped dep is indistinguishable
+            // from the same dep on a fully interpreted resolve.
+            resolveEscaped: (token, options, arity, resolutionStack) => {
+                if (arity === "all") {
+                    return this.resolveAll(token, options, resolutionStack);
+                }
+                if (arity === "optional") {
+                    return this.resolveOptional(token, options, resolutionStack);
+                }
+                if (options === undefined) {
+                    return this.resolveFromContext(token, resolutionStack);
+                }
+                return this.resolve(token, options, resolutionStack);
+            },
+            // Dispatches exactly as #resolveDepAsync does, for the async lane's escapes.
+            resolveEscapedAsync: (token, options, arity, resolutionStack) => {
+                if (arity === "all") {
+                    return this.resolveAllAsync(token, options, resolutionStack, UNOWNED_BRANCH);
+                }
+                if (arity === "optional") {
+                    return this.resolveOptionalAsync(token, options, resolutionStack, UNOWNED_BRANCH);
+                }
+                if (options === undefined) {
+                    return this.resolveAsyncFromContext(token, resolutionStack, UNOWNED_BRANCH);
+                }
+                return this.resolveAsync(token, options, resolutionStack, UNOWNED_BRANCH);
+            },
+        }));
+    }
     /** The async lane's plan for a statically-visible transient binding, mirroring the sync getter. */
     #getAsyncInstantiationPlan(binding) {
         const registryVersion = this.#lookup.chainVersion();
         const activationVersion = this.#chainActivationVersion();
         if (registryVersion !== this.#asyncPlanRegistryVersion || activationVersion !== this.#asyncPlanActivationVersion) {
-            this.#asyncPlanByBindingId.clear();
+            if (this.#asyncPlanByBindingId === undefined) {
+                this.#asyncPlanByBindingId = new Map();
+            }
+            else {
+                this.#asyncPlanByBindingId.clear();
+            }
             this.#asyncPlanRegistryVersion = registryVersion;
             this.#asyncPlanActivationVersion = activationVersion;
         }
-        const cached = this.#asyncPlanByBindingId.get(binding.id);
+        const plans = this.#asyncPlanByBindingId;
+        const cached = plans.get(binding.identifier);
         if (cached !== undefined) {
             return cached;
         }
-        const compiled = this.#planCompiler.compileAsync(binding);
+        const compiled = this.#compiler().compileAsync(binding);
         if (compiled === PLAN_RETRY) {
             // Lifecycle metadata not discovered yet — the fallback resolve discovers it; retry then.
             return null;
         }
-        this.#asyncPlanByBindingId.set(binding.id, compiled);
+        plans.set(binding.identifier, compiled);
         return compiled;
     }
     resolve(token, options, resolutionStack, precomputedCriterion) {
@@ -430,7 +555,7 @@ export class DependencyResolver {
                 return binding.instance;
             }
             // An async materialization already in flight must not be raced by a second, sync one.
-            if (this.#scope.getInflight(binding.id) !== undefined) {
+            if (this.#scope.getInflight(binding.identifier) !== undefined) {
                 throw new AsyncResolutionError(resolutionStack[0]?.tokenName ?? tokenName(binding.token), tokenName(binding.token));
             }
             if (this.#scope.isClosed) {
@@ -442,7 +567,7 @@ export class DependencyResolver {
             if (cachedScoped !== SCOPED_MISS) {
                 return cachedScoped;
             }
-            if (this.#scope.getInflight(binding.id) !== undefined) {
+            if (this.#scope.getInflight(binding.identifier) !== undefined) {
                 throw new AsyncResolutionError(resolutionStack[0]?.tokenName ?? tokenName(binding.token), tokenName(binding.token));
             }
             if (this.#scope.isClosed) {
@@ -453,7 +578,7 @@ export class DependencyResolver {
         const tokenDisplayName = frame.tokenName;
         const resolutionSet = enterResolutionPath(resolutionStack, frame);
         try {
-            const needsActivation = owner.#activation.needsActivation(binding);
+            const needsActivation = owner.#activationNeed().needsActivation(binding);
             if (!needsActivation && scope === "transient" && binding.kind === "dynamic") {
                 const resolutionCtx = this.#acquireSyncResolutionContext(resolutionStack, options);
                 const dynamicResult = binding.factory(resolutionCtx);
@@ -467,7 +592,7 @@ export class DependencyResolver {
                 : undefined;
             const instance = this.#instantiateSync(binding, resolutionCtx, resolutionStack);
             this.#mirrorPostConstructFromOwner(binding, owner);
-            const activated = owner.#activation.refreshAfterFirstInstantiation(binding, needsActivation)
+            const activated = owner.#activationNeed().refreshAfterFirstInstantiation(binding, needsActivation)
                 ? owner.#lifecycle.runActivationSync(resolutionCtx, binding, instance, owner.#metadataReader)
                 : instance;
             if (scope === "singleton") {
@@ -484,7 +609,16 @@ export class DependencyResolver {
         }
     }
     /** Path-continuing resolution handed to the ambient slot while an accessor class constructs. */
+    // The ambient resolution a top-level construction hands its accessors: the lent root stack is one
+    // array for the resolver's lifetime, so the pair of closures over it is built once and reused.
+    #rootAmbientResolution;
     #ambientResolutionFor(resolutionStack) {
+        if (resolutionStack === this.rootStack) {
+            return (this.#rootAmbientResolution ??= this.#buildAmbientResolution(resolutionStack));
+        }
+        return this.#buildAmbientResolution(resolutionStack);
+    }
+    #buildAmbientResolution(resolutionStack) {
         return {
             resolve: (token, options) => options === undefined
                 ? this.resolveFromContext(token, resolutionStack)
@@ -572,6 +706,19 @@ export class DependencyResolver {
         return this.resolve(dep.token, options, resolutionStack, singleCriterionForSlot(dep));
     }
     resolveOptional(token, options, resolutionStack, precomputedCriterion) {
+        if (options === undefined) {
+            // The lane a plain resolve takes: a lone default in this registry is the answer, predicate-free by
+            // construction, and a root that keeps no records has nothing else that could hold the token.
+            const fastBinding = this.#registry.getFastDefault(token);
+            if (fastBinding !== undefined) {
+                if (fastBinding.kind !== "alias") {
+                    return this.#resolveDefaultEntry(fastBinding, this, resolutionStack);
+                }
+            }
+            else if (this.#parent === undefined && !this.#registry.isRecordMapBuilt) {
+                return undefined;
+            }
+        }
         const entry = this.#findBinding(token, options, resolutionStack, precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined));
         if (entry === undefined) {
             return undefined;
@@ -595,6 +742,80 @@ export class DependencyResolver {
         }
         return resolved;
     }
+    /**
+     * A root-level, options-less collection read through its memo: the value list when it is stable,
+     * the candidate list otherwise.
+     *
+     * @remarks Its own entry rather than a branch in `resolveAll`, so the options lane keeps the exact
+     * shape it had; the container routes a top-level read with no options here.
+     */
+    resolveRootCollection(token) {
+        const resolutionStack = this.rootStack;
+        const memo = this.#rootCollection(token, resolutionStack);
+        if (memo.values !== undefined && memo.activationVersion === this.#chainActivationVersion()) {
+            return memo.values;
+        }
+        const { candidates } = memo;
+        const resolved = new Array(candidates.length);
+        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);
+        return resolved;
+    }
+    /** The async twin of `resolveRootCollection`: a stable value list settles 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);
+        }
+        return Promise.all(memo.candidates.map((candidate) => this.#resolveCandidateAsync(candidate, undefined, resolutionStack, UNOWNED_BRANCH))).then((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.
+     */
+    #rootCollection(token, resolutionStack) {
+        const memo = this.#lookup.collection(token);
+        if (memo !== undefined) {
+            return memo;
+        }
+        const candidates = this.#candidateBindings(token, undefined, resolutionStack);
+        const entry = { candidates, values: undefined, activationVersion: -1 };
+        this.#settleCollectionValues(entry);
+        this.#lookup.rememberCollection(token, entry);
+        return entry;
+    }
+    /**
+     * 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
+     * version the memo is keyed on. A member still to be materialised leaves the list unfilled.
+     */
+    #settleCollectionValues(entry) {
+        if (entry.values !== undefined || this.#chainActivationVersion() !== 0) {
+            return;
+        }
+        const { candidates } = entry;
+        for (let index = 0; index < candidates.length; index += 1) {
+            if (!isStableCollectionMember(candidates[index])) {
+                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.
+        entry.values = candidates.map(stableMemberValue);
+        entry.activationVersion = 0;
+    }
     /** Every binding in the chain a `resolveAll` request matches, in chain order. */
     #candidateBindings(token, options, resolutionStack) {
         if (options !== undefined) {
@@ -648,7 +869,7 @@ export class DependencyResolver {
             }
         }
         else if (this.#scope.isChild) {
-            const cachedScoped = this.#scope.readScoped(binding.id);
+            const cachedScoped = this.#scope.readScoped(binding.identifier);
             if (cachedScoped !== SCOPED_MISS) {
                 return Promise.resolve(cachedScoped);
             }
@@ -685,7 +906,7 @@ export class DependencyResolver {
                 return binding.instance;
             }
             // In-flight dedup: concurrent callers share the first creation.
-            const inflight = this.#scope.getInflight(binding.id);
+            const inflight = this.#scope.getInflight(binding.identifier);
             if (inflight !== undefined) {
                 return inflight;
             }
@@ -699,7 +920,7 @@ export class DependencyResolver {
                 return cachedScoped;
             }
             // In-flight dedup, scoped flavor: one instance per scope even under concurrency.
-            const inflight = this.#scope.getInflight(binding.id);
+            const inflight = this.#scope.getInflight(binding.identifier);
             if (inflight !== undefined) {
                 return inflight;
             }
@@ -711,7 +932,7 @@ export class DependencyResolver {
         // This level appends to its own branch and never unwinds.
         const levelStack = extendResolutionBranch(resolutionStack, branchDepth, frame);
         const levelDepth = branchDepthOf(levelStack);
-        const needsActivation = owner.#activation.needsActivation(binding);
+        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") {
@@ -727,26 +948,26 @@ export class DependencyResolver {
             // 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);
-                this.#scope.clearInflight(binding.id);
+                this.#scope.clearInflight(binding.identifier);
                 return activated;
             }, (error) => {
-                this.#scope.clearInflight(binding.id);
+                this.#scope.clearInflight(binding.identifier);
                 throw error;
             });
-            this.#scope.setInflight(binding.id, singletonPromise);
+            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.id);
+                this.#scope.clearInflight(binding.identifier);
                 return activated;
             }, (error) => {
-                this.#scope.clearInflight(binding.id);
+                this.#scope.clearInflight(binding.identifier);
                 throw error;
             });
-            this.#scope.setInflight(binding.id, scopedPromise);
+            this.#scope.setInflight(binding.identifier, scopedPromise);
             return await scopedPromise;
         }
         return await this.#instantiateAndActivateAsync(binding, resolutionCtx, levelStack, levelDepth, needsActivation, owner);
@@ -766,7 +987,7 @@ export class DependencyResolver {
     async #instantiateAndActivateAsync(binding, ctx, resolutionStack, branchDepth, needsActivation, owner) {
         const instance = await this.#instantiateAsync(binding, ctx, resolutionStack, branchDepth);
         this.#mirrorPostConstructFromOwner(binding, owner);
-        if (!owner.#activation.refreshAfterFirstInstantiation(binding, needsActivation)) {
+        if (!owner.#activationNeed().refreshAfterFirstInstantiation(binding, needsActivation)) {
             return instance;
         }
         return owner.#lifecycle.runActivation(ctx, binding, instance, owner.#metadataReader);
@@ -916,12 +1137,12 @@ export class DependencyResolver {
     /** A constant with no activation anywhere resolves to its value with no pipeline at all. */
     #isPlainConstant(binding) {
         return (binding.kind === "constant" &&
-            binding.onActivation === undefined &&
+            binding.activationHook === undefined &&
             (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token)));
     }
     /** Whether either an own hook or a container-level hook would run for this binding. */
     #hasAnyActivation(binding) {
-        if (binding.onActivation !== undefined) {
+        if (binding.activationHook !== undefined) {
             return true;
         }
         return this.#lifecycle.activationVersion !== 0 && this.#lifecycle.hasActivationHandlers(binding.token);
@@ -936,7 +1157,7 @@ export class DependencyResolver {
         if (!this.#scope.isChild) {
             throw new MissingScopeContextError(tokenName(binding.token));
         }
-        return this.#scope.readScoped(binding.id);
+        return this.#scope.readScoped(binding.identifier);
     }
     // 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.
@@ -1137,7 +1358,7 @@ export class DependencyResolver {
     #resolveCandidateSync(binding, options, resolutionStack) {
         // Fan-outs are dominated by constants: with no activation hook anywhere in the chain, a
         // hook-free constant is plain no matter which container owns it — skip the owner probe.
-        if (binding.kind === "constant" && binding.onActivation === undefined && this.#chainActivationVersion() === 0) {
+        if (binding.kind === "constant" && binding.activationHook === undefined && this.#chainActivationVersion() === 0) {
             return binding.value;
         }
         const owner = this.#ownerOf(binding);
@@ -1157,7 +1378,7 @@ export class DependencyResolver {
         return this.#resolveBinding(binding, options, resolutionStack, owner);
     }
     #resolveCandidateAsync(binding, options, resolutionStack, branchDepth) {
-        if (binding.kind === "constant" && binding.onActivation === undefined && this.#chainActivationVersion() === 0) {
+        if (binding.kind === "constant" && binding.activationHook === undefined && this.#chainActivationVersion() === 0) {
             return Promise.resolve(binding.value);
         }
         const owner = this.#ownerOf(binding);
@@ -1173,16 +1394,25 @@ export class DependencyResolver {
             }
             return owner.#resolveBindingAsync(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.
+        if (options === undefined &&
+            binding.scope === "transient" &&
+            (binding.kind === "dynamic" || binding.kind === "dynamic-async") &&
+            !owner.#hasAnyActivation(binding)) {
+            return this.#resolveTransientDynamicAsyncFromContext(binding, resolutionStack, branchDepth);
+        }
         return this.#resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner);
     }
     /** The resolver whose registry holds `binding` — `this` (the common case) when it is own. */
     #ownerOf(binding) {
         // A root resolver can only hold its own bindings, so the per-candidate id probe is chain-only.
-        if (this.#parent === undefined || this.#registry.getById(binding.id) !== undefined) {
+        if (this.#parent === undefined || this.#registry.getById(binding.identifier) !== undefined) {
             return this;
         }
         for (let current = this.#parent; current !== undefined; current = current.#parent) {
-            if (current.#registry.getById(binding.id) !== undefined) {
+            if (current.#registry.getById(binding.identifier) !== undefined) {
                 return current;
             }
         }
@@ -1196,7 +1426,7 @@ export class DependencyResolver {
         if (existing !== undefined) {
             return existing;
         }
-        const frame = buildResolutionFrame(tokenName(binding.token), binding.scope, binding.id, binding.kind, binding.slot);
+        const frame = buildResolutionFrame(tokenName(binding.token), binding.scope, binding.identifier, binding.kind, binding.slot);
         binding.frame = frame;
         return frame;
     }
@@ -1234,6 +1464,17 @@ export class DependencyResolver {
         return created;
     }
 }
+/** A constant whose value is its answer on every read: no own hook, and the caller has ruled out container hooks. */
+// A cached singleton reads like a constant until a registry change evicts it, which also drops the memo.
+function isStableCollectionMember(binding) {
+    if (binding.kind === "alias" || binding.activationHook !== undefined) {
+        return false;
+    }
+    return binding.kind === "constant" || (binding.scope === "singleton" && binding.instance !== NO_INSTANCE);
+}
+function stableMemberValue(binding) {
+    return binding.kind === "constant" ? binding.value : binding.instance;
+}
 function anyPredicate(bindings) {
     for (let index = 0; index < bindings.length; index += 1) {
         if (bindings[index].predicate !== undefined) {