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

package/src/errors.ts

@@ -212,6 +212,27 @@ export class MissingContainerContextError extends DiError {
   }
 }
 
+/**
+ * A fluent chain was refined before a `to*()` call gave it a binding to refine.
+ *
+ * @remarks The builder types make this unreachable from TypeScript — `bind()` returns
+ * `BindToBuilder`, which exposes only `to*()`. It exists for JavaScript callers and for anyone who
+ * casts past the types, so the misuse fails loudly instead of mutating nothing.
+ *
+ * @since 0.5.0-canary.8
+ */
+export class ChainNotRegisteredError extends DiError {
+  readonly code = "CHAIN_NOT_REGISTERED";
+  readonly tokenName: string;
+
+  constructor(tokenName: string) {
+    super(
+      `Cannot refine the binding for token '${tokenName}' before choosing a target. Call a to*() method first — for example .to(SomeClass), .toConstantValue(value) or .toDynamic(factory).`,
+    );
+    this.tokenName = tokenName;
+  }
+}
+
 /**
  * @since 0.3.16-canary.0
  */
@@ -227,6 +248,23 @@ export class RebindUnboundTokenError extends DiError {
   }
 }
 
+/**
+ * `toSelf()` on a token that is not a class, so there is nothing to construct.
+ *
+ * @since 0.5.0-canary.9
+ */
+export class SelfBindingRequiresClassError extends DiError {
+  readonly code = "SELF_BINDING_REQUIRES_CLASS";
+  readonly tokenName: string;
+
+  constructor(tokenName: string) {
+    super(
+      `toSelf() needs the token to be the class it constructs, and '${tokenName}' is not a class. Use .to(SomeClass) to name the implementation, or bind the class itself with container.bind(SomeClass).toSelf().`,
+    );
+    this.tokenName = tokenName;
+  }
+}
+
 /**
  * @since 0.3.16-canary.0
  */

package/src/index.ts

@@ -36,7 +36,8 @@ export type {
 export { Container } from "#/container/container";
 export type { Container as ContainerInterface, ContainerStatic } from "#/container/container";
 
-export { effectiveBindingScope } from "#/resolution/binding-scope";
+// `effectiveBindingScope` is deliberately absent: it reads a `Binding`, which is internal, and no
+// public API hands one out. `BindingSnapshot.scope` and `GraphNode.scope` are the public answers.
 export { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolution/resolve-options";
 
 // Introspection types
@@ -85,6 +86,7 @@ export {
   AsyncDeactivationError,
   AsyncModuleLoadError,
   AsyncResolutionError,
+  ChainNotRegisteredError,
   CircularDependencyError,
   DiError,
   DisposedContainerError,
@@ -95,6 +97,7 @@ export {
   NoMatchingBindingError,
   RebindUnboundTokenError,
   ScopeViolationError,
+  SelfBindingRequiresClassError,
   SyncDisposalNotSupportedError,
   TokenNotBoundError,
 } from "#/errors";

package/src/introspection/inspector.ts

@@ -60,10 +60,9 @@ export class Inspector {
   }
 
   inspect(): ContainerSnapshot {
-    const snapshots = this.allBindingSnapshots();
     return {
-      ownBindings: snapshots,
-      cachedSingletonCount: this.#scope.getAllSingletons().size,
+      ownBindings: this.#registry.allBindings().map((binding) => this.#toSnapshot(binding)),
+      cachedSingletonCount: this.#scope.cachedSingletons().length,
       hasParent: this.#hasParent,
       isDisposed: this.#isDisposed(),
     };
@@ -109,12 +108,7 @@ export class Inspector {
     };
   }
 
-  private allBindingSnapshots(): ReadonlyArray<BindingSnapshot> {
-    return this.#registry.allBindings().map((binding) => this.#toSnapshot(binding));
-  }
-
   #toSnapshot(binding: Binding): BindingSnapshot {
-    const scope = effectiveBindingScope(binding);
     const slot: BindingSnapshot["slot"] =
       binding.slot.name !== undefined
         ? { name: binding.slot.name, tags: binding.slot.tags }
@@ -122,7 +116,7 @@ export class Inspector {
     return {
       tokenName: tokenName(binding.token),
       kind: binding.kind,
-      scope,
+      scope: effectiveBindingScope(binding),
       slot,
       id: binding.id,
     };

package/src/metadata/metadata-keys.ts

@@ -12,13 +12,10 @@ export const LIFECYCLE_KEY: unique symbol = Symbol("di:lifecycle");
 export const INJECT_ACCESSOR_KEY: unique symbol = Symbol("di:inject-accessor");
 
 /**
- * The well-known symbol used by TC39 Stage 3 decorator transforms to store class metadata.
+ * The symbol TC39 Stage 3 decorator transforms store class metadata under.
  *
- * `Symbol.metadata` is defined natively once the runtime ships the full TC39 decorator
- * proposal.  Until then (current Node.js / browsers), Babel and esbuild both fall back to
- * `Symbol.for("Symbol.metadata")` — a global-registry symbol with the same string key.
- * Resolving it here once keeps the reader and the decorator transforms in sync regardless
- * of which path is taken.
+ * @remarks Falls back to the global-registry symbol, which is what Babel and esbuild emit until
+ * a runtime ships `Symbol.metadata` natively.
  *
  * @since 0.3.16-canary.0
  */

package/src/registry.ts

@@ -1,45 +1,7 @@
 import type { Binding } from "#/binding";
 import { bindingSlotEquals, bindingSlotToString } from "#/binding";
 import type { Token } from "#/token";
-import type { BindingIdentifier, Constructor, DependencyKey } from "#/types";
-
-// Superset of every binding kind's fields, used to normalize hidden classes below.
-type BindingFieldSuperset = Binding & {
-  readonly scope?: unknown;
-  readonly target?: unknown;
-  readonly factory?: unknown;
-  readonly deps?: unknown;
-  readonly value?: unknown;
-  readonly onActivation?: unknown;
-  readonly onDeactivation?: unknown;
-};
-
-/**
- * Rebuilds a binding with every kind's fields in one fixed key order, so all stored
- * bindings share a single V8 hidden class. Mixed binding kinds otherwise turn the
- * resolver's hot property reads (kind/scope/factory/...) megamorphic, which costs
- * ~30% throughput in processes that exercise many kinds. The value-erasing cast is
- * safe: every declared field is copied verbatim and `kind` stays the discriminant.
- */
-function normalizeBindingShape(binding: Binding): Binding {
-  const source = binding as BindingFieldSuperset;
-  return {
-    kind: source.kind,
-    id: source.id,
-    inFlight: false,
-    frame: undefined,
-    token: source.token,
-    slot: source.slot,
-    predicate: source.predicate,
-    scope: source.scope,
-    target: source.target,
-    factory: source.factory,
-    deps: source.deps,
-    value: source.value,
-    onActivation: source.onActivation,
-    onDeactivation: source.onDeactivation,
-  } as Binding;
-}
+import type { BindingIdentifier, BindingTag, Constructor, DependencyKey } from "#/types";
 
 /**
  * @since 0.3.16-canary.0
@@ -51,31 +13,45 @@ export class BindingRegistry {
   readonly #bindings = new Map<DependencyKey, Array<Binding>>();
   // Fast lookup by binding ID
   readonly #byId = new Map<BindingIdentifier, Binding>();
-  // Fast lookup for slot { name, tags: [] }
-  readonly #simpleNamed = new Map<DependencyKey, Map<string, Binding>>();
+  // Fast lookup for slot { name, tags: [] } — unallocated until a named binding is registered.
+  #simpleNamed: Map<DependencyKey, Map<string, Binding>> | undefined;
   // Fast path for one default slot binding with no predicate
   readonly #fastDefault = new Map<DependencyKey, Binding>();
-  // Fast lookup for slot { name: undefined, tags: [[key, value]] } with no predicate
-  readonly #simpleTagged = new Map<DependencyKey, Map<string, Map<unknown, Binding>>>();
+  // Fast lookup for slot { name: undefined, tags: [[key, value]] } with no predicate — likewise
+  // unallocated until a tagged binding is registered.
+  #simpleTagged: Map<DependencyKey, Map<string, Map<unknown, Binding>>> | undefined;
 
   /** Monotonic version — increments on every mutation. */
   get version(): number {
     return this.#version;
   }
 
-  /** Add or replace binding using slot-aware last-wins. Returns the displaced binding, if any. */
-  add(uncommittedBinding: Binding): Binding | undefined {
+  /**
+   * Registers a mutation the indexes don't care about (a fluent chain refining scope or an
+   * activation hook in place), so version-stamped resolver caches still invalidate.
+   */
+  touch(): void {
+    this.#version += 1;
+  }
+
+  /**
+   * Add or replace binding using slot-aware last-wins. Returns the displaced binding, if any.
+   *
+   * @remarks The binding is stored by reference — it must come from `createBinding`, which is
+   * what guarantees the single hidden class the resolver's hot reads depend on.
+   */
+  add(binding: Binding): Binding | undefined {
     this.#version += 1;
-    const binding = normalizeBindingShape(uncommittedBinding);
     const key = binding.token as DependencyKey;
-    // ✓ TS6.0: Map.getOrInsert (ES2025) replaces the manual get+check+set upsert
+    // Eager, not computed: a bind is usually the token's first, so the fallback is usually the
+    // one that gets stored — and the computed form would add a call to allocating it anyway.
     const bindingsForToken = this.#bindings.getOrInsert(key, []);
 
     // Only apply last-wins for slot-based bindings (not predicate-only)
     let displacedBinding: Binding | undefined;
-    if (!this.#isPurePredicateBinding(binding)) {
+    if (!isPurePredicateBinding(binding)) {
       const existingIndex = bindingsForToken.findIndex(
-        (candidate) => !this.#isPurePredicateBinding(candidate) && bindingSlotEquals(candidate.slot, binding.slot),
+        (candidate) => !isPurePredicateBinding(candidate) && bindingSlotEquals(candidate.slot, binding.slot),
       );
       if (existingIndex !== -1) {
         displacedBinding = bindingsForToken[existingIndex]!;
@@ -100,8 +76,8 @@ export class BindingRegistry {
     const key = token as DependencyKey;
     const bindingsForToken = this.#bindings.get(key) ?? [];
     this.#bindings.delete(key);
-    this.#simpleNamed.delete(key);
-    this.#simpleTagged.delete(key);
+    this.#simpleNamed?.delete(key);
+    this.#simpleTagged?.delete(key);
     this.#fastDefault.delete(key);
     for (const binding of bindingsForToken) {
       this.#byId.delete(binding.id);
@@ -128,8 +104,8 @@ export class BindingRegistry {
       this.#deindexSimpleTaggedBinding(key, binding);
       if (bindingsForToken.length === 0) {
         this.#bindings.delete(key);
-        this.#simpleNamed.delete(key);
-        this.#simpleTagged.delete(key);
+        this.#simpleNamed?.delete(key);
+        this.#simpleTagged?.delete(key);
         this.#fastDefault.delete(key);
       } else {
         this.#refreshFastDefaultForToken(key);
@@ -170,19 +146,19 @@ export class BindingRegistry {
     const all = this.allBindings();
     this.#bindings.clear();
     this.#byId.clear();
-    this.#simpleNamed.clear();
-    this.#simpleTagged.clear();
+    this.#simpleNamed?.clear();
+    this.#simpleTagged?.clear();
     this.#fastDefault.clear();
     return all;
   }
 
   getSimpleNamed(token: Token<unknown> | Constructor, name: string): Binding | undefined {
-    return this.#simpleNamed.get(token as DependencyKey)?.get(name);
+    return this.#simpleNamed?.get(token as DependencyKey)?.get(name);
   }
 
   getSimpleTagged(token: Token<unknown> | Constructor, tagKey: string, tagValue: unknown): Binding | undefined {
     return this.#simpleTagged
-      .get(token as DependencyKey)
+      ?.get(token as DependencyKey)
       ?.get(tagKey)
       ?.get(tagValue);
   }
@@ -198,23 +174,23 @@ export class BindingRegistry {
   }
 
   #indexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
-    const slot = binding.slot;
-    if (slot.name !== undefined || slot.tags.length !== 1 || binding.predicate !== undefined) {
+    const tag = simpleTagOf(binding);
+    if (tag === undefined) {
       return;
     }
-    const [tagKey, tagValue] = slot.tags[0]!;
-    const byTagKey = this.#simpleTagged.getOrInsert(tokenKey, new Map<string, Map<unknown, Binding>>());
+    const [tagKey, tagValue] = tag;
+    const byTagKey = (this.#simpleTagged ??= new Map()).getOrInsert(tokenKey, new Map<string, Map<unknown, Binding>>());
     const byTagValue = byTagKey.getOrInsert(tagKey, new Map<unknown, Binding>());
     byTagValue.set(tagValue, binding);
   }
 
   #deindexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
-    const slot = binding.slot;
-    if (slot.name !== undefined || slot.tags.length !== 1 || binding.predicate !== undefined) {
+    const tag = simpleTagOf(binding);
+    if (tag === undefined) {
       return;
     }
-    const [tagKey, tagValue] = slot.tags[0]!;
-    const byTagKey = this.#simpleTagged.get(tokenKey);
+    const [tagKey, tagValue] = tag;
+    const byTagKey = this.#simpleTagged?.get(tokenKey);
     if (byTagKey === undefined) {
       return;
     }
@@ -228,59 +204,79 @@ export class BindingRegistry {
       if (byTagValue.size === 0) {
         byTagKey.delete(tagKey);
         if (byTagKey.size === 0) {
-          this.#simpleTagged.delete(tokenKey);
+          this.#simpleTagged!.delete(tokenKey);
         }
       }
     }
   }
 
-  #isPurePredicateBinding(binding: Binding): boolean {
-    const slot = binding.slot;
-    const hasPredicate = binding.predicate !== undefined;
-    const hasConstraint = slot.name !== undefined || slot.tags.length > 0;
-    // Pure predicate = has predicate but no slot constraint (name/tags)
-    return hasPredicate && !hasConstraint;
-  }
-
   #indexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
-    const slot = binding.slot;
-    if (slot.name === undefined || slot.tags.length > 0) {
+    const name = simpleNameOf(binding);
+    if (name === undefined) {
       return;
     }
-    const bindingsByName = this.#simpleNamed.getOrInsert(tokenKey, new Map<string, Binding>());
-    bindingsByName.set(slot.name, binding);
+    const bindingsByName = (this.#simpleNamed ??= new Map()).getOrInsert(tokenKey, new Map<string, Binding>());
+    bindingsByName.set(name, binding);
   }
 
   #deindexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
-    const slot = binding.slot;
-    if (slot.name === undefined || slot.tags.length > 0) {
+    const name = simpleNameOf(binding);
+    if (name === undefined) {
       return;
     }
-    const bindingsByName = this.#simpleNamed.get(tokenKey);
+    const bindingsByName = this.#simpleNamed?.get(tokenKey);
     if (bindingsByName === undefined) {
       return;
     }
-    const currentBinding = bindingsByName.get(slot.name);
-    if (currentBinding?.id === binding.id) {
-      bindingsByName.delete(slot.name);
+    if (bindingsByName.get(name)?.id === binding.id) {
+      bindingsByName.delete(name);
       if (bindingsByName.size === 0) {
-        this.#simpleNamed.delete(tokenKey);
+        this.#simpleNamed!.delete(tokenKey);
       }
     }
   }
 
   #refreshFastDefaultForToken(tokenKey: DependencyKey): void {
     const bindingsForToken = this.#bindings.get(tokenKey);
-    if (bindingsForToken === undefined || bindingsForToken.length !== 1) {
-      this.#fastDefault.delete(tokenKey);
-      return;
-    }
-    const onlyBinding = bindingsForToken[0]!;
-    const isDefaultSlot = onlyBinding.slot.name === undefined && onlyBinding.slot.tags.length === 0;
-    if (!isDefaultSlot || onlyBinding.predicate !== undefined) {
-      this.#fastDefault.delete(tokenKey);
+    const onlyBinding = bindingsForToken?.length === 1 ? bindingsForToken[0]! : undefined;
+    if (onlyBinding !== undefined && isDefaultSlotBinding(onlyBinding)) {
+      this.#fastDefault.set(tokenKey, onlyBinding);
       return;
     }
-    this.#fastDefault.set(tokenKey, onlyBinding);
+    this.#fastDefault.delete(tokenKey);
   }
+
+  /** Whether the deferred table behind `#simpleNamed` has had to be built. */
+  get isBuilt(): boolean {
+    return this.#simpleNamed !== undefined;
+  }
+}
+
+/** The name a binding is indexed under, or `undefined` when its slot is more than a plain name. */
+function simpleNameOf(binding: Binding): string | undefined {
+  const { name, tags } = binding.slot;
+  return name !== undefined && tags.length === 0 ? name : undefined;
+}
+
+/**
+ * The tag a binding is indexed under, or `undefined` when its slot is more than one plain tag.
+ *
+ * @remarks A predicate is excluded here — unlike the name index — because the tag index is read
+ * without a re-check, so an indexed hit must be unconditional.
+ */
+function simpleTagOf(binding: Binding): BindingTag | undefined {
+  const { name, tags } = binding.slot;
+  return name === undefined && tags.length === 1 && binding.predicate === undefined ? tags[0] : undefined;
+}
+
+/** A binding nothing has to be matched against: the default slot, no predicate. */
+function isDefaultSlotBinding(binding: Binding): boolean {
+  const { name, tags } = binding.slot;
+  return name === undefined && tags.length === 0 && binding.predicate === undefined;
+}
+
+/** A predicate with no slot constraint: last-wins does not apply to it. */
+function isPurePredicateBinding(binding: Binding): boolean {
+  const { name, tags } = binding.slot;
+  return binding.predicate !== undefined && name === undefined && tags.length === 0;
 }

package/src/resolution/activation-need.ts

@@ -0,0 +1,85 @@
+/**
+ * Per binding: does resolving it have to go through the activation pipeline?
+ *
+ * @remarks Versioned on the lifecycle manager plus the own registry, since `onActivation` can be
+ * registered at any time and a rebind mints binding ids the memo must not keep forever.
+ */
+import type { Binding } from "#/binding";
+import type { BindingRegistry } from "#/registry";
+import type { ClassIntrospector } from "#/resolution/class-introspector";
+import type { LifecycleManager } from "#/resolution/lifecycle";
+import type { BindingIdentifier } from "#/types";
+
+/**
+ * @since 0.5.0-canary.8
+ */
+export class ActivationNeedCache {
+  readonly #needByBindingId = new Map<BindingIdentifier, boolean>();
+  #version = -1;
+  readonly #lifecycle: LifecycleManager;
+  readonly #classes: ClassIntrospector;
+  readonly #registry: BindingRegistry;
+
+  constructor(lifecycle: LifecycleManager, classes: ClassIntrospector, registry: BindingRegistry) {
+    this.#lifecycle = lifecycle;
+    this.#classes = classes;
+    this.#registry = registry;
+  }
+
+  needsActivation<const Value>(binding: Binding<Value>): boolean {
+    // 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.
+    if (binding.kind !== "alias" && binding.onActivation !== undefined) {
+      return true;
+    }
+    const lifecycleVersion = this.#lifecycle.activationVersion;
+    // No hooks registered anywhere and none on the binding: only classes can still surprise us,
+    // via a @postConstruct we have not looked for yet.
+    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;
+    }
+    const cached = this.#needByBindingId.get(binding.id);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const needsActivation =
+      binding.kind === "class" ? this.#classNeedsActivation(binding) : this.#nonClassNeedsActivation(binding);
+    this.#needByBindingId.set(binding.id, needsActivation);
+    return needsActivation;
+  }
+
+  /**
+   * Settles a class binding's answer once its lifecycle metadata has actually been read, which
+   * only happens on the first instantiation.
+   *
+   * @returns the answer to use for this resolve — possibly now `false` where it was a
+   * conservative `true`.
+   */
+  refreshAfterFirstInstantiation<Value>(binding: Binding<Value>, needsActivation: boolean): boolean {
+    if (binding.kind !== "class" || this.#classes.knownPostConstruct(binding.target) !== undefined) {
+      return needsActivation;
+    }
+    this.#classes.discoverPostConstruct(binding.target);
+    this.#needByBindingId.delete(binding.id);
+    return this.needsActivation(binding);
+  }
+
+  // Own hooks are answered before the memo, so both computations cover the memoizable rest only.
+  #classNeedsActivation<const Value>(binding: Binding<Value> & { kind: "class" }): boolean {
+    if (this.#lifecycle.hasActivationHandlers(binding.token)) {
+      return true;
+    }
+    // Unknown lifecycle metadata: activate once so the first instantiation can settle it.
+    return this.#classes.knownPostConstruct(binding.target) !== false;
+  }
+
+  #nonClassNeedsActivation<const Value>(binding: Binding<Value>): boolean {
+    return this.#lifecycle.hasActivationHandlers(binding.token);
+  }
+}

package/src/resolution/binding-lookup-cache.ts

@@ -0,0 +1,148 @@
+/**
+ * Options-less token → terminal binding, memoized per container chain.
+ *
+ * @see `ARCHITECTURE.md` — why these caches form their own parent chain.
+ */
+import type { Binding } from "#/binding";
+import type { BindingRegistry } from "#/registry";
+import type { Token } from "#/token";
+import type { Constructor } from "#/types";
+
+/**
+ * A token's terminal binding with alias hops already folded, plus the container that owns it.
+ *
+ * @typeParam Owner - the resolver type, kept generic so this module stays free of resolver internals
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface DefaultLookupEntry<Owner> {
+  readonly binding: Binding;
+  readonly owner: Owner;
+}
+
+/**
+ * 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;
+
+/**
+ * @since 0.5.0-canary.8
+ */
+const newNameToEntryMap = <Owner>(): Map<string, DefaultLookupEntry<Owner> | null> => new Map();
+
+/**
+ * @since 0.5.0-canary.9
+ */
+export class BindingLookupCache<Owner> {
+  readonly #byToken = new Map<Token<unknown> | Constructor, DefaultLookupEntry<Owner> | null>();
+  #version = -1;
+  // One entry in front of the map: the two shapes that reach here — an alias, and a token owned by
+  // a parent — are both resolved in a loop over the same token. `null` is a real answer, so absence
+  // is tracked by the token slot rather than by the entry.
+  #lastToken: Token<unknown> | Constructor | undefined;
+  #lastEntry: DefaultLookupEntry<Owner> | null = null;
+  readonly #byTokenAndName = new Map<Token<unknown> | Constructor, Map<string, DefaultLookupEntry<Owner> | null>>();
+  #namedVersion = -1;
+
+  readonly #registry: BindingRegistry;
+  readonly #owner: Owner;
+  readonly #parent: BindingLookupCache<Owner> | undefined;
+
+  constructor(registry: BindingRegistry, owner: Owner, parent: BindingLookupCache<Owner> | undefined) {
+    this.#registry = registry;
+    this.#owner = owner;
+    this.#parent = parent;
+  }
+
+  /** Summed registry versions of this cache's whole chain — the memo stamp. */
+  chainVersion(): number {
+    let version = this.#registry.version;
+    for (let cache = this.#parent; cache !== undefined; cache = cache.#parent) {
+      version += cache.#registry.version;
+    }
+    return version;
+  }
+
+  /** `null` when the token's shape needs the full selection path. */
+  defaultEntry(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
+    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 = this.#byToken.get(token);
+    if (entry === undefined) {
+      entry = this.#foldAliases(token);
+      this.#byToken.set(token, entry);
+    }
+    this.#lastToken = token;
+    this.#lastEntry = entry;
+    return entry;
+  }
+
+  /** `null` when the name's shape needs the full selection path. */
+  namedEntry(token: Token<unknown> | Constructor, name: string): DefaultLookupEntry<Owner> | null {
+    const version = this.chainVersion();
+    if (version !== this.#namedVersion) {
+      this.#byTokenAndName.clear();
+      this.#namedVersion = version;
+    }
+    // Computed, not eager: this runs on every named resolve, and `getOrInsert(token, new Map())`
+    // would allocate a Map per call only to discard it on the hit that follows.
+    const byName = this.#byTokenAndName.getOrInsertComputed(token, newNameToEntryMap);
+    let entry = byName.get(name);
+    if (entry === undefined) {
+      entry = this.#findNamedInChain(token, name);
+      byName.set(name, entry);
+    }
+    return entry;
+  }
+
+  #foldAliases(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
+    let current = token;
+    for (let hop = 0; hop < ALIAS_HOP_LIMIT; hop += 1) {
+      const entry = this.#findDefaultInChain(current);
+      if (entry === null) {
+        return null;
+      }
+      if (entry.binding.kind !== "alias") {
+        return entry;
+      }
+      current = entry.binding.target;
+    }
+    return null;
+  }
+
+  #findDefaultInChain(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
+    const fast = this.#registry.getFastDefault(token);
+    if (fast !== undefined) {
+      return { binding: fast, owner: this.#owner };
+    }
+    // A level with non-fast bindings (multi-slot / predicate) needs full selection — bail.
+    if (this.#registry.has(token)) {
+      return null;
+    }
+    return this.#parent === undefined ? null : this.#parent.#findDefaultInChain(token);
+  }
+
+  #findNamedInChain(token: Token<unknown> | Constructor, name: string): DefaultLookupEntry<Owner> | null {
+    const named = this.#registry.getSimpleNamed(token, name);
+    if (named !== undefined) {
+      // Predicates need a live context; aliases carry options through the full path.
+      if (named.predicate !== undefined || named.kind === "alias") {
+        return null;
+      }
+      return { binding: named, owner: this.#owner };
+    }
+    if (this.#registry.has(token)) {
+      return null;
+    }
+    return this.#parent === undefined ? null : this.#parent.#findNamedInChain(token, name);
+  }
+}