@codefast/di 0.10.1 → 0.11.0

package/dist/introspection/dependency-graph.js

@@ -1,3 +1,4 @@
+import { stringifyTagValue } from "#core/binding";
 import { effectiveBindingScope } from "#core/binding-scope";
 import { slotName } from "#core/tag";
 import { tokenName } from "#core/token";
@@ -41,18 +42,31 @@ function edgeLabel(ref, index) {
     const criterion = name !== undefined
         ? `name:${name}`
         : firstPlainTag !== undefined
-            ? `tag:${firstPlainTag.key.name}=${String(firstPlainTag.value)}`
+            ? `tag:${firstPlainTag.key.name}=${stringifyTagValue(firstPlainTag.value)}`
             : `[${index}]`;
     return ref.optional ? `${criterion} optional` : criterion;
 }
-function bindingLookup(sourceRegistry, fallbackRegistry) {
-    return (token) => {
-        const own = sourceRegistry.getAll(token);
-        if (own.length > 0 || fallbackRegistry === undefined) {
-            return own;
+/**
+ * The bindings a dependency reaches, found the way resolution finds them.
+ *
+ * @remarks A single dependency stops at the nearest registry holding a binding its slot matches, and
+ * a collection gathers every registry's matches — `resolve` and `resolveAll` respectively.
+ */
+function dependencyTargets(chain, ref) {
+    if (ref.multi) {
+        const gathered = [];
+        for (const registry of chain) {
+            gathered.push(...matchingTargets(registry.getAll(ref.token), ref));
+        }
+        return gathered;
+    }
+    for (const registry of chain) {
+        const targets = matchingTargets(registry.getAll(ref.token), ref);
+        if (targets.length > 0) {
+            return targets;
         }
-        return fallbackRegistry.getAll(token);
-    };
+    }
+    return [];
 }
 /** The placeholder node an optional-but-unbound dependency points at, minted once per token. */
 function unboundNodeIdFor(accumulator, dependency) {
@@ -73,8 +87,8 @@ function unboundNodeIdFor(accumulator, dependency) {
     });
     return id;
 }
-function addDependencyEdges(accumulator, from, ref, index, lookup) {
-    const targets = matchingTargets(lookup(ref.token), ref);
+function addDependencyEdges(accumulator, from, ref, index, chain) {
+    const targets = dependencyTargets(chain, ref);
     const label = edgeLabel(ref, index);
     if (targets.length === 0) {
         // A required-but-unbound dependency is validate()'s story, not the graph's.
@@ -108,25 +122,25 @@ function addDependencyEdges(accumulator, from, ref, index, lookup) {
     }
 }
 /** What one binding declares up front — a class's params, a factory's descriptors, an alias's target. */
-function addBindingEdges(accumulator, binding, metadataReader, lookup) {
+function addBindingEdges(accumulator, binding, metadataReader, chain) {
     if (binding.kind === "class") {
         const meta = metadataReader.getConstructorMetadata(binding.target);
         if (meta !== undefined) {
             for (const [index, param] of meta.params.entries()) {
-                addDependencyEdges(accumulator, String(binding.identifier), param, index, lookup);
+                addDependencyEdges(accumulator, String(binding.identifier), param, index, chain);
             }
         }
         return;
     }
     if (binding.kind === "resolved" || binding.kind === "resolved-async") {
         for (const [index, dependency] of binding.deps.entries()) {
-            addDependencyEdges(accumulator, String(binding.identifier), dependency, index, lookup);
+            addDependencyEdges(accumulator, String(binding.identifier), dependency, index, chain);
         }
         return;
     }
     if (binding.kind === "alias") {
         const aliasRef = { token: binding.target, optional: false, multi: false };
-        for (const target of matchingTargets(lookup(binding.target), aliasRef)) {
+        for (const target of dependencyTargets(chain, aliasRef)) {
             accumulator.edges.push({
                 from: String(binding.identifier),
                 to: String(target.identifier),
@@ -136,9 +150,9 @@ function addBindingEdges(accumulator, binding, metadataReader, lookup) {
         }
     }
 }
-function addRegistryBindings(accumulator, sourceRegistry, metadataReader, fromParent, fallbackRegistry) {
-    const lookup = bindingLookup(sourceRegistry, fallbackRegistry);
-    for (const binding of sourceRegistry.allBindings()) {
+/** Adds the nodes of `chain[0]`, the registry the chain starts at, and the edges each of its bindings declares. */
+function addRegistryBindings(accumulator, chain, metadataReader, fromParent) {
+    for (const binding of chain[0].allBindings()) {
         accumulator.nodes.push({
             id: String(binding.identifier),
             tokenName: tokenName(binding.token),
@@ -147,20 +161,29 @@ function addRegistryBindings(accumulator, sourceRegistry, metadataReader, fromPa
             scope: effectiveBindingScope(binding),
             fromParent,
         });
-        addBindingEdges(accumulator, binding, metadataReader, lookup);
+        addBindingEdges(accumulator, binding, metadataReader, chain);
     }
 }
 /**
- * Builds the JSON dependency graph of a registry's bindings, optionally including the parent's.
+ * Builds the JSON dependency graph of a registry's bindings, optionally including its ancestors'.
+ *
+ * @param registry - The registry whose bindings the graph is for.
+ * @param metadataReader - The reader class dependencies are read through.
+ * @param options - Whether the ancestors' bindings join the graph.
+ * @param ancestorRegistries - The ancestor containers' registries, nearest first.
  *
  * @since 0.3.16-canary.0
  */
-export function buildDependencyGraph(registry, metadataReader, options, parentRegistry) {
+export function buildDependencyGraph(registry, metadataReader, options, ancestorRegistries = []) {
     const accumulator = { nodes: [], edges: [], unboundNodeIds: new Map() };
     const includesParent = options?.includeParent === true;
-    addRegistryBindings(accumulator, registry, metadataReader, false, includesParent ? parentRegistry : undefined);
-    if (includesParent && parentRegistry !== undefined) {
-        addRegistryBindings(accumulator, parentRegistry, metadataReader, true);
+    if (!includesParent) {
+        addRegistryBindings(accumulator, [registry], metadataReader, false);
+        return { nodes: accumulator.nodes, edges: accumulator.edges, includesParent };
+    }
+    const chain = [registry, ...ancestorRegistries];
+    for (let depth = 0; depth < chain.length; depth += 1) {
+        addRegistryBindings(accumulator, chain.slice(depth), metadataReader, depth > 0);
     }
     return { nodes: accumulator.nodes, edges: accumulator.edges, includesParent };
 }

package/dist/introspection/graph-adapters/reactflow.js

@@ -1,9 +1,9 @@
 /**
- * Initial grid layout: React Flow expects concrete positions; viewers re-layout anyway.
+ * Initial grid cell, in the pixels React Flow positions in: a starting layout viewers re-lay out,
+ * fixed by no contract.
  *
  * @since 0.3.16-canary.0
  */
-const GRID_COLUMN_COUNT = 5;
 const GRID_CELL_WIDTH_PX = 200;
 const GRID_CELL_HEIGHT_PX = 100;
 /**
@@ -12,6 +12,8 @@ const GRID_CELL_HEIGHT_PX = 100;
  * @since 0.5.0-canary.7
  */
 export function toReactFlowGraph(graph) {
+    // A square grid over the graph: as many columns as rows, derived from the node count.
+    const columnCount = Math.max(1, Math.ceil(Math.sqrt(graph.nodes.length)));
     const nodes = graph.nodes.map((node, idx) => ({
         id: node.id,
         data: {
@@ -22,8 +24,8 @@ export function toReactFlowGraph(graph) {
             fromParent: node.fromParent,
         },
         position: {
-            x: (idx % GRID_COLUMN_COUNT) * GRID_CELL_WIDTH_PX,
-            y: Math.floor(idx / GRID_COLUMN_COUNT) * GRID_CELL_HEIGHT_PX,
+            x: (idx % columnCount) * GRID_CELL_WIDTH_PX,
+            y: Math.floor(idx / columnCount) * GRID_CELL_HEIGHT_PX,
         },
     }));
     const edges = graph.edges.map((edge, idx) => ({

package/dist/introspection/inspector.js

@@ -1,5 +1,6 @@
 import { effectiveBindingScope } from "#core/binding-scope";
 import { tokenName } from "#core/token";
+import { DefaultConstraintContext } from "#resolution/context";
 import { selectAllBindings } from "#resolution/select/binding-select";
 // ── Inspector ────────────────────────────────────────────────────────────────────────────────────────────────────────
 /**
@@ -38,17 +39,13 @@ export class Inspector {
         }
         const bindings = this.#registry.getAll(token);
         // An existence probe answers ambiguity with `true` — several matches still exist; only
-        // resolution has to pick one.
-        return bindings.length > 0 && selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0;
+        // resolution has to pick one. A default-slot alias answers any criteria by forwarding them.
+        return (bindings.length > 0 &&
+            (selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0 ||
+                this.#registry.getDefaultSlotBinding(token)?.kind === "alias"));
     }
     #makeConstraintContext(options) {
-        return {
-            resolutionPath: [],
-            resolutionStack: [],
-            parent: undefined,
-            ancestors: [],
-            currentResolveOptions: options,
-        };
+        return new DefaultConstraintContext([], options);
     }
     #toSnapshot(binding) {
         // Aliased, not copied: slot tags are frozen where they are built, so a caller's write throws

package/dist/lifecycle/lifecycle-manager.js

@@ -97,7 +97,11 @@ export class LifecycleManager {
         let activatedInstance = instance;
         // 1. @postConstruct() — must be sync (instance fully constructed per TC39 order)
         for (const methodName of lifecycleMethods(binding, metadataReader, "postConstruct")) {
-            if (callHook(activatedInstance, methodName) instanceof Promise) {
+            const hookResult = callHook(activatedInstance, methodName);
+            if (hookResult instanceof Promise) {
+                // The hook has already run; adopt its rejection so a failing async hook cannot become an
+                // unhandled rejection that ends the process, then report the sync-lane violation.
+                void hookResult.catch(() => { });
                 throw new AsyncActivationError(tokenName(binding.token), "postConstruct", methodName);
             }
         }
@@ -105,6 +109,7 @@ export class LifecycleManager {
         if (binding.kind !== "alias" && binding.activationHook !== undefined) {
             const activationResult = binding.activationHook(resolutionContext, activatedInstance);
             if (activationResult instanceof Promise) {
+                void activationResult.catch(() => { });
                 throw new AsyncActivationError(tokenName(binding.token), "onActivation");
             }
             activatedInstance = activationResult;
@@ -116,6 +121,7 @@ export class LifecycleManager {
             for (const hook of containerHooks) {
                 const activationResult = hook(resolutionContext, activatedInstance);
                 if (activationResult instanceof Promise) {
+                    void activationResult.catch(() => { });
                     throw new AsyncActivationError(tokenDisplayName, "onActivation");
                 }
                 activatedInstance = activationResult;
@@ -159,6 +165,9 @@ export class LifecycleManager {
             for (const hook of containerHooks) {
                 const hookResult = hook(instance);
                 if (hookResult instanceof Promise) {
+                    // The hook has already run; adopt its rejection so a failing async hook cannot become an
+                    // unhandled rejection that ends the process, then report the sync-lane violation.
+                    void hookResult.catch(() => { });
                     throw new AsyncDeactivationError(tokenDisplayName);
                 }
             }
@@ -167,12 +176,15 @@ export class LifecycleManager {
         if (binding.kind !== "alias" && binding.deactivationHook !== undefined) {
             const hookResult = binding.deactivationHook(instance);
             if (hookResult instanceof Promise) {
+                void hookResult.catch(() => { });
                 throw new AsyncDeactivationError(tokenDisplayName);
             }
         }
         // 3. @preDestroy()
         for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
-            if (callHook(instance, methodName) instanceof Promise) {
+            const hookResult = callHook(instance, methodName);
+            if (hookResult instanceof Promise) {
+                void hookResult.catch(() => { });
                 throw new AsyncDeactivationError(tokenDisplayName);
             }
         }

package/dist/lifecycle/scope-manager.js

@@ -39,22 +39,39 @@ export class ScopeManager {
         }
         binding.instance = instance;
     }
+    // A removal only clears the instance; the list keeps its entry until a read compacts it, so a
+    // teardown of a hundred singletons is a hundred field writes, not a hundred splices.
+    #compacted = true;
     /** Every binding in this container holding a cached singleton. */
     cachedSingletons() {
-        return this.#singletonBindings ?? EMPTY_BINDINGS;
+        const tracked = this.#singletonBindings;
+        if (tracked === undefined) {
+            return EMPTY_BINDINGS;
+        }
+        if (!this.#compacted) {
+            // Latest materialization wins the position: walk from the end keeping each live binding once.
+            const seen = new Set();
+            const live = [];
+            for (let index = tracked.length - 1; index >= 0; index -= 1) {
+                const binding = tracked[index];
+                if (binding.instance !== NO_INSTANCE && !seen.has(binding)) {
+                    seen.add(binding);
+                    live.push(binding);
+                }
+            }
+            live.reverse();
+            this.#singletonBindings = live;
+            this.#compacted = true;
+            return live;
+        }
+        return tracked;
     }
     deleteSingleton(binding) {
         if (binding.instance === NO_INSTANCE) {
             return false;
         }
         binding.instance = NO_INSTANCE;
-        const tracked = this.#singletonBindings;
-        if (tracked !== undefined) {
-            const index = tracked.indexOf(binding);
-            if (index !== -1) {
-                tracked.splice(index, 1);
-            }
-        }
+        this.#compacted = false;
         return true;
     }
     /** Swaps a re-slotted binding's tracked entry, so teardown pairs the instance with the live object. */
@@ -112,10 +129,11 @@ export class ScopeManager {
     clearAll() {
         const tracked = this.#singletonBindings;
         if (tracked !== undefined) {
-            for (const binding of tracked) {
-                binding.instance = NO_INSTANCE;
+            for (let index = 0; index < tracked.length; index += 1) {
+                tracked[index].instance = NO_INSTANCE;
             }
             tracked.length = 0;
+            this.#compacted = true;
         }
         this.#inflight?.clear();
         this.#scoped?.clear();

package/dist/metadata/verifying-metadata-reader.d.ts

@@ -1,14 +1,15 @@
 /**
  * Wraps a foreign {@link MetadataReader} so its answers are verified before anything dereferences
- * them.
+ * them, and asked for once per class.
  */
 import type { MetadataReader } from "#metadata/metadata-types";
 /**
- * The reader a container should hand its resolver: verified when it came from outside.
+ * The reader a container should hand its resolver: verified and memoized when it came from outside.
  *
  * @remarks The decorator reader writes the metadata it later reads, so there is nothing to check and
  * nothing to pay — a container that supplies no reader of its own is left on the same code path it
- * has always taken. A supplied reader is a claim, and only its callers can be charged for checking.
+ * has always taken. A supplied reader is a claim, and only its callers can be charged for checking;
+ * it is asked about a class once, however many containers read through it.
  *
  * @since 0.6.0
  */

package/dist/metadata/verifying-metadata-reader.js

@@ -1,17 +1,34 @@
 /**
  * Wraps a foreign {@link MetadataReader} so its answers are verified before anything dereferences
- * them.
+ * them, and asked for once per class.
  */
 import { defaultMetadataReader } from "#metadata/symbol-metadata-reader";
 import { verifyAccessorMetadata, verifyConstructorMetadata, verifyLifecycleMetadata, } from "#resolution/cache/class-introspector";
 // Wrapping a wrapper would stack a layer per child container, so each one is remembered.
 const verifyingReaders = new WeakSet();
+// One wrapper per foreign reader, so every container handed that reader shares its answers.
+const wrapperByReader = new WeakMap();
+// `null` records a verified "no metadata", so an absent answer is not asked for again either.
+function memoized(ask) {
+    const answers = new WeakMap();
+    return (target) => {
+        const known = answers.get(target);
+        if (known !== undefined) {
+            return known === null ? undefined : known;
+        }
+        // Stored only after `ask` returns, so an answer that fails verification is asked for, and fails, again.
+        const answer = ask(target);
+        answers.set(target, answer ?? null);
+        return answer;
+    };
+}
 /**
- * The reader a container should hand its resolver: verified when it came from outside.
+ * The reader a container should hand its resolver: verified and memoized when it came from outside.
  *
  * @remarks The decorator reader writes the metadata it later reads, so there is nothing to check and
  * nothing to pay — a container that supplies no reader of its own is left on the same code path it
- * has always taken. A supplied reader is a claim, and only its callers can be charged for checking.
+ * has always taken. A supplied reader is a claim, and only its callers can be charged for checking;
+ * it is asked about a class once, however many containers read through it.
  *
  * @since 0.6.0
  */
@@ -19,13 +36,18 @@ export function verifyingMetadataReader(reader) {
     if (reader === defaultMetadataReader || verifyingReaders.has(reader)) {
         return reader;
     }
+    const existing = wrapperByReader.get(reader);
+    if (existing !== undefined) {
+        return existing;
+    }
     const verifying = {
-        getConstructorMetadata: (target) => verifyConstructorMetadata(reader, target),
-        getLifecycleMetadata: (target) => verifyLifecycleMetadata(reader, target),
+        getConstructorMetadata: memoized((target) => verifyConstructorMetadata(reader, target)),
+        getLifecycleMetadata: memoized((target) => verifyLifecycleMetadata(reader, target)),
         ...(reader.getAccessorMetadata === undefined
             ? {}
-            : { getAccessorMetadata: (target) => verifyAccessorMetadata(reader, target) }),
+            : { getAccessorMetadata: memoized((target) => verifyAccessorMetadata(reader, target)) }),
     };
     verifyingReaders.add(verifying);
+    wrapperByReader.set(reader, verifying);
     return verifying;
 }

package/dist/resolution/async-fan-out.d.ts

@@ -0,0 +1,12 @@
+/** Settles the concurrent dependencies of one async level and reports a failure in declaration order. */
+/**
+ * Applies `apply` to every dependency's settled value, or rejects with the first failure in declaration order.
+ *
+ * @remarks Siblings start concurrently, and `Promise.all` alone would report whichever rejection
+ * settles first — a fact about microtask depth, not about the graph. The synchronous lanes report
+ * the first failing dependency in declaration order, so this does too: the happy path is `Promise.all`,
+ * and only a failure waits for every sibling to settle and then picks the earliest one that did not.
+ *
+ * @since 0.11.0
+ */
+export declare function settleInOrder<Result>(pending: ReadonlyArray<unknown>, apply: (values: Array<unknown>) => Result): Promise<Result>;

package/dist/resolution/async-fan-out.js

@@ -0,0 +1,26 @@
+/** Settles the concurrent dependencies of one async level and reports a failure in declaration order. */
+/**
+ * Applies `apply` to every dependency's settled value, or rejects with the first failure in declaration order.
+ *
+ * @remarks Siblings start concurrently, and `Promise.all` alone would report whichever rejection
+ * settles first — a fact about microtask depth, not about the graph. The synchronous lanes report
+ * the first failing dependency in declaration order, so this does too: the happy path is `Promise.all`,
+ * and only a failure waits for every sibling to settle and then picks the earliest one that did not.
+ *
+ * @since 0.11.0
+ */
+export function settleInOrder(pending, apply) {
+    return Promise.all(pending).then(apply, () => firstRejectionInOrder(pending));
+}
+function firstRejectionInOrder(pending) {
+    return Promise.allSettled(pending).then((results) => {
+        for (let index = 0; index < results.length; index += 1) {
+            const result = results[index];
+            if (result.status === "rejected") {
+                throw result.reason;
+            }
+        }
+        // Unreachable: this branch only runs once `Promise.all` has rejected, so a rejection is settled.
+        throw new Error("settleInOrder: a rejected fan-out settled with no rejection");
+    });
+}

package/dist/resolution/cache/activation-need.d.ts

@@ -17,7 +17,6 @@ export declare class ActivationNeedCache {
     #private;
     constructor(lifecycle: LifecycleManager, classes: ClassIntrospector, registry: BindingRegistry);
     /** Whether an answer the early returns could not give has had to allocate the memo. */
-    get isMemoBuilt(): boolean;
     needsActivation<Value>(binding: Binding<Value>): boolean;
     /**
      * Settles a class binding's answer once its lifecycle metadata has actually been read, which

package/dist/resolution/cache/activation-need.js

@@ -1,13 +1,10 @@
+import { NO_ACTIVATION_STAMP } from "#core/binding";
 /**
  * A per-binding cache of whether activation work — hooks or `@postConstruct` — is needed on resolve.
  *
  * @since 0.5.0-canary.8
  */
 export class ActivationNeedCache {
-    // Allocated by the first answer the early returns cannot give, so a hook-free container that
-    // resolves no class or alias never pays for it.
-    #needByBindingId;
-    #version = -1;
     #lifecycle;
     #classes;
     #registry;
@@ -17,9 +14,6 @@ export class ActivationNeedCache {
         this.#registry = registry;
     }
     /** Whether an answer the early returns could not give has had to allocate the memo. */
-    get isMemoBuilt() {
-        return this.#needByBindingId !== undefined;
-    }
     needsActivation(binding) {
         // The chain writes a binding's own hook in place with no version anything here can see, so it
         // is read fresh on every call; the memo covers only container hooks and lifecycle metadata.
@@ -32,19 +26,18 @@ export class ActivationNeedCache {
         if (lifecycleVersion === 0 && binding.kind !== "class" && binding.kind !== "alias") {
             return false;
         }
-        // The registry version evicts entries for binding ids a rebind has retired.
-        const version = lifecycleVersion + this.#registry.version;
-        if (this.#version !== version) {
-            this.#needByBindingId?.clear();
-            this.#version = version;
+        // The stamp is the version pair the answer was computed under, doubled, plus the answer: a
+        // registry or lifecycle mutation moves the version and retires every stamp at once.
+        const stampBase = (lifecycleVersion + this.#registry.version) * 2;
+        const stamp = binding.activationStamp;
+        if (stamp === stampBase) {
+            return false;
         }
-        const memo = (this.#needByBindingId ??= new Map());
-        const cached = memo.get(binding.identifier);
-        if (cached !== undefined) {
-            return cached;
+        if (stamp === stampBase + 1) {
+            return true;
         }
         const needsActivation = binding.kind === "class" ? this.#classNeedsActivation(binding) : this.#nonClassNeedsActivation(binding);
-        memo.set(binding.identifier, needsActivation);
+        binding.activationStamp = needsActivation ? stampBase + 1 : stampBase;
         return needsActivation;
     }
     /**
@@ -59,7 +52,7 @@ export class ActivationNeedCache {
             return needsActivation;
         }
         this.#classes.discoverPostConstruct(binding.target);
-        this.#needByBindingId?.delete(binding.identifier);
+        binding.activationStamp = NO_ACTIVATION_STAMP;
         return this.needsActivation(binding);
     }
     // Own hooks are answered before the memo, so both computations cover the memoizable rest only.

package/dist/resolution/cache/binding-lookup-cache.d.ts

@@ -34,13 +34,6 @@ export interface CollectionEntry {
     values: ReadonlyArray<unknown> | undefined;
     activationVersion: number;
 }
-/**
- * Alias folding gives up past this many hops and defers to the full resolve loop, whose
- * Set-based traversal detects genuine cycles exactly rather than by an arbitrary cap.
- *
- * @since 0.5.0-canary.8
- */
-export declare const ALIAS_HOP_LIMIT = 32;
 /**
  * A version-stamped cache of binding lookups by token and criterion across the container chain.
  *

package/dist/resolution/cache/binding-lookup-cache.js

@@ -1,12 +1,5 @@
 import { getOrInsertComputed } from "#core/map-upsert";
 import { stateEpoch } from "#core/state-epoch";
-/**
- * Alias folding gives up past this many hops and defers to the full resolve loop, whose
- * Set-based traversal detects genuine cycles exactly rather than by an arbitrary cap.
- *
- * @since 0.5.0-canary.8
- */
-export const ALIAS_HOP_LIMIT = 32;
 const newTagToEntryMap = () => new Map();
 const newNameToTagMap = () => new Map();
 /**
@@ -76,15 +69,19 @@ export class BindingLookupCache {
     }
     /** `null` when the token's shape needs the full selection path. */
     defaultEntry(token) {
+        // The repeat hit is the whole method, small enough for a hot caller to inline; the fill is the miss.
+        if (token === this.#lastToken && this.chainVersion() === this.#version) {
+            return this.#lastEntry;
+        }
+        return this.#defaultEntryMiss(token);
+    }
+    #defaultEntryMiss(token) {
         const version = this.chainVersion();
         if (version !== this.#version) {
             this.#byToken?.clear();
             this.#version = version;
             this.#lastToken = undefined;
         }
-        else if (token === this.#lastToken) {
-            return this.#lastEntry;
-        }
         let entry;
         if (this.#lastToken === undefined) {
             // First token this cache generation sees: answer from the walk and defer the map entirely.
@@ -159,7 +156,12 @@ export class BindingLookupCache {
     #findPairInChain(token, nameCriterion, tag) {
         const found = this.#registry.getPairTagged(token, nameCriterion, tag);
         if (found !== undefined) {
-            return found.predicate !== undefined || found.kind === "alias" ? null : { binding: found, owner: this.#owner };
+            // A predicate candidate at this level can win the more-specific rule's first step, which this
+            // lane cannot weigh; an alias carries options through the full path. Either declines to selection.
+            if (found.kind === "alias" || this.#registry.hasPredicateCandidate(token)) {
+                return null;
+            }
+            return { binding: found, owner: this.#owner };
         }
         if (this.#registry.has(token)) {
             return null;
@@ -180,19 +182,30 @@ export class BindingLookupCache {
     rememberCollection(token, entry) {
         (this.#collections ??= new Map()).set(token, entry);
     }
+    /**
+     * Follows alias hops to the terminal entry, or declines with `null` on a cycle, which the full
+     * resolve loop reports.
+     *
+     * @remarks The origin and the current token are compared by hand and the set holds only what lies
+     * between them, so the common one-hop alias allocates nothing and any chain is folded exactly.
+     */
     #foldAliases(token) {
         let current = token;
-        for (let hop = 0; hop < ALIAS_HOP_LIMIT; hop += 1) {
+        let visited;
+        for (;;) {
             const entry = this.#findDefaultInChain(current);
-            if (entry === null) {
+            if (entry === null || entry.binding.kind !== "alias") {
+                return entry;
+            }
+            const next = entry.binding.target;
+            if (next === token || next === current || visited?.has(next) === true) {
                 return null;
             }
-            if (entry.binding.kind !== "alias") {
-                return entry;
+            if (current !== token) {
+                (visited ??= new Set()).add(current);
             }
-            current = entry.binding.target;
+            current = next;
         }
-        return null;
     }
     #findDefaultInChain(token) {
         const fast = this.#registry.getFastDefault(token);

package/dist/resolution/cache/class-introspector.d.ts

@@ -54,6 +54,17 @@ export declare class ClassIntrospector {
     #private;
     constructor(reader: MetadataReader, container: Container, inherited: ClassIntrospector | undefined);
     constructorMetadata(target: Constructor): ConstructorMetadata | undefined;
+    /**
+     * The nearest ancestor's own constructor metadata, for a subclass that declares none of its own.
+     *
+     * @remarks Constructor metadata is never borrowed down the chain, so a subclass with an implicit
+     * constructor would be built with zero arguments; this lets the resolver name the base whose
+     * declared deps the subclass silently drops.
+     */
+    inheritedConstructorMetadata(target: Constructor): {
+        base: Constructor;
+        metadata: ConstructorMetadata;
+    } | undefined;
     /**
      * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
      *

package/dist/resolution/cache/class-introspector.js

@@ -173,6 +173,24 @@ export class ClassIntrospector {
         (caches.constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
         return metadata;
     }
+    /**
+     * The nearest ancestor's own constructor metadata, for a subclass that declares none of its own.
+     *
+     * @remarks Constructor metadata is never borrowed down the chain, so a subclass with an implicit
+     * constructor would be built with zero arguments; this lets the resolver name the base whose
+     * declared deps the subclass silently drops.
+     */
+    inheritedConstructorMetadata(target) {
+        let current = Object.getPrototypeOf(target);
+        while (typeof current === "function" && current !== Function.prototype) {
+            const metadata = this.constructorMetadata(current);
+            if (metadata !== undefined) {
+                return { base: current, metadata };
+            }
+            current = Object.getPrototypeOf(current);
+        }
+        return undefined;
+    }
     /**
      * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
      *