@codefast/di 0.7.0 → 0.8.0

package/src/resolution/resolver.ts

@@ -3,7 +3,7 @@ import type { Container } from "#/container/container";
 import type { Binding, ConstantBinding, DynamicAsyncBinding, DynamicBinding } from "#/core/binding";
 import { NO_INSTANCE } from "#/core/binding";
 import type { BindingRegistry } from "#/core/registry";
-import { NO_TAG_KEYS } from "#/core/tag";
+import { NO_TAG_KEYS, slotNameCriterionOf } from "#/core/tag";
 import type { Token } from "#/core/token";
 import { tokenName } from "#/core/token";
 import type {
@@ -28,7 +28,7 @@ import {
   TokenNotBoundError,
 } from "#/errors/errors";
 import type { DependencySlot } from "#/injection/resolve-options";
-import { isNameOnlyOptions, resolveOptionsForSlot, singleTagOnlyOf } from "#/injection/resolve-options";
+import { resolveOptionsForSlot, singleCriterionForSlot, singleCriterionOnlyOf } from "#/injection/resolve-options";
 import type { LifecycleManager } from "#/lifecycle/lifecycle-manager";
 import type { ScopeManager } from "#/lifecycle/scope-manager";
 import { SCOPED_MISS } from "#/lifecycle/scope-manager";
@@ -71,6 +71,8 @@ const ROOT_CONSTRAINT_CONTEXT = {
 };
 
 /**
+ * The resolution engine driving binding selection, instantiation, scoping, and lifecycle hooks.
+ *
  * @since 0.3.16-canary.0
  */
 export class DependencyResolver implements ResolverCallbacks {
@@ -161,45 +163,44 @@ export class DependencyResolver implements ResolverCallbacks {
 
   // ── Binding lookup ─────────────────────────────────────────────────────────────────────────────────────────────────
 
+  /**
+   * Finds the binding a request selects in this container, walking up to the parent on a miss.
+   *
+   * @remarks `singleCriterion` is the request's lone criterion, folded once by the caller so alias
+   * hops and parent walks do not re-fold it — `undefined` when the request carries none or several.
+   */
   #findBinding(
     token: Token<unknown> | Constructor,
     options: ResolveOptions | undefined,
     resolutionStack: Array<ResolutionFrame>,
+    singleCriterion: BindingTag | undefined,
   ): DefaultLookupEntry<DependencyResolver> | undefined {
     if (options === undefined) {
       const fastDefaultBinding = this.#registry.getFastDefault(token);
       if (fastDefaultBinding !== undefined) {
         return { binding: fastDefaultBinding, owner: this };
       }
-    } else if (isNameOnlyOptions(options)) {
-      const namedBinding = this.#registry.getSimpleNamed(token, options.name);
-      if (namedBinding !== undefined && this.#matchesBindingFast(namedBinding, options, resolutionStack)) {
-        return { binding: namedBinding, owner: this };
-      }
-    } else {
-      const singleTag = singleTagOnlyOf(options);
-      if (singleTag !== undefined) {
-        const tagged = this.#registry.getSimpleTagged(token, singleTag);
-        if (tagged !== undefined && this.#satisfiesPredicate(tagged, options, resolutionStack)) {
-          return { binding: tagged, owner: this };
-        }
-      } else if (
-        options.name === undefined &&
-        // 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 name-less multi-tag request matches only name-less tagged slots, and every such slot
-        // lives in one of the two tag indexes — so their union is the whole candidate set and the
-        // token's full list never needs scanning. Selection still owns predicates and specificity.
-        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);
+    } else if (singleCriterion !== undefined) {
+      const indexed = this.#registry.getSimpleTagged(token, singleCriterion);
+      if (indexed !== undefined && 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);
@@ -208,7 +209,7 @@ export class DependencyResolver implements ResolverCallbacks {
       // specificity to weigh and no ambiguity to report.
       const selected =
         bindings.length === 1
-          ? this.#matchesBindingFast(bindings[0]!, options, resolutionStack)
+          ? matchesSlot(bindings[0]!.slot, options) && this.#satisfiesPredicate(bindings[0]!, options, resolutionStack)
             ? bindings[0]
             : undefined
           : selectBinding(bindings, options, this.#makeConstraintContext(resolutionStack, options), tokenName(token));
@@ -217,7 +218,7 @@ export class DependencyResolver implements ResolverCallbacks {
       }
     }
     if (this.#parent !== undefined) {
-      return this.#parent.#findBinding(token, options, resolutionStack);
+      return this.#parent.#findBinding(token, options, resolutionStack, singleCriterion);
     }
     return undefined;
   }
@@ -232,10 +233,14 @@ export class DependencyResolver implements ResolverCallbacks {
     token: Token<unknown> | Constructor,
     options: ResolveOptions | undefined,
     resolutionStack: Array<ResolutionFrame>,
+    precomputedCriterion?: BindingTag | null,
   ): DefaultLookupEntry<DependencyResolver> {
+    // `null` is a caller's "folded: none" — only an absent precomputation re-folds.
+    const singleCriterion =
+      precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined);
     let currentToken = token;
     let visitedAliasTokens: Set<Token<unknown> | Constructor> | undefined;
-    let found = this.#findBinding(currentToken, options, resolutionStack);
+    let found = this.#findBinding(currentToken, options, resolutionStack, singleCriterion);
 
     while (found !== undefined && found.binding.kind === "alias") {
       const target = found.binding.target;
@@ -245,7 +250,7 @@ export class DependencyResolver implements ResolverCallbacks {
       }
       visitedAliasTokens.add(target);
       currentToken = target;
-      found = this.#findBinding(currentToken, options, resolutionStack);
+      found = this.#findBinding(currentToken, options, resolutionStack, singleCriterion);
     }
 
     if (found === undefined) {
@@ -270,7 +275,7 @@ export class DependencyResolver implements ResolverCallbacks {
     token: Token<unknown> | Constructor,
     options: ResolveOptions | undefined,
   ): DefaultLookupEntry<DependencyResolver> | undefined {
-    return this.#findBinding(token, options, []);
+    return this.#findBinding(token, options, [], singleCriterionOnlyOf(options));
   }
 
   /**
@@ -427,22 +432,14 @@ export class DependencyResolver implements ResolverCallbacks {
       const entry = this.#lookup.defaultEntry(token);
       return entry === null ? null : { binding: entry.binding };
     },
-    // Exactly what #findBinding's named lane accepts, minus the half that reads a path: a predicate
-    // is the compiler's cue to leave the selection to the runtime.
-    lookupPathIndependentNamedEntry: (token, options) => {
-      const entry = this.#lookup.namedEntry(token, options.name);
-      if (entry === null || entry.binding.predicate !== undefined || !matchesSlot(entry.binding.slot, options)) {
+    // 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;
       }
-      return { binding: entry.binding };
-    },
-    // The named rule verbatim, on the single-tag lane's memo.
-    lookupPathIndependentTaggedEntry: (token, options) => {
-      const singleTag = singleTagOnlyOf(options);
-      if (singleTag === undefined) {
-        return null;
-      }
-      const entry = this.#lookup.taggedEntry(token, singleTag);
+      const entry = this.#lookup.taggedEntry(token, singleCriterion);
       if (entry === null || entry.binding.predicate !== undefined || !matchesSlot(entry.binding.slot, options)) {
         return null;
       }
@@ -506,40 +503,30 @@ export class DependencyResolver implements ResolverCallbacks {
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
     resolutionStack: Array<ResolutionFrame>,
+    precomputedCriterion?: BindingTag | null,
   ): Value {
-    // Name-only fast lane: memoized lookup, dispatching just the shapes whose
-    // semantics involve no resolution context (constants, cached singletons).
-    if (options !== undefined && isNameOnlyOptions(options)) {
-      const namedEntry = this.#lookup.namedEntry(token, options.name);
-      if (namedEntry !== null) {
-        const namedBinding = namedEntry.binding;
-        if (namedEntry.owner.#isPlainConstant(namedBinding)) {
-          return namedBinding.value as Value;
-        }
-        if (namedBinding.scope === "singleton" && namedBinding.instance !== NO_INSTANCE) {
-          return namedBinding.instance as Value;
-        }
-        // Everything else keeps the full path (context, activation, guards).
-      }
-    } else if (options !== undefined) {
-      // Single-tag fast lane: the named lane's tagged twin, memoizing the chain walk.
-      const singleTag = singleTagOnlyOf(options);
-      if (singleTag !== undefined) {
-        const taggedEntry = this.#lookup.taggedEntry(token, singleTag);
-        if (taggedEntry !== null) {
-          const taggedBinding = taggedEntry.binding;
-          if (taggedEntry.owner.#isPlainConstant(taggedBinding)) {
-            return taggedBinding.value as Value;
+    // Single-criterion fast lane (a lone name folds here too): memoized lookup, dispatching just
+    // the shapes whose semantics involve no resolution context (constants, cached singletons).
+    let singleCriterion: BindingTag | undefined;
+    if (options !== undefined) {
+      singleCriterion =
+        precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined);
+      if (singleCriterion !== undefined) {
+        const indexedEntry = this.#lookup.taggedEntry(token, singleCriterion);
+        if (indexedEntry !== null) {
+          const indexedBinding = indexedEntry.binding;
+          if (indexedEntry.owner.#isPlainConstant(indexedBinding)) {
+            return indexedBinding.value as Value;
           }
-          if (taggedBinding.scope === "singleton" && taggedBinding.instance !== NO_INSTANCE) {
-            return taggedBinding.instance as Value;
+          if (indexedBinding.scope === "singleton" && indexedBinding.instance !== NO_INSTANCE) {
+            return indexedBinding.instance as Value;
           }
           // Everything else keeps the full path (context, activation, guards).
         }
       }
     }
 
-    const { binding, owner } = this.#requireBinding(token, options, resolutionStack);
+    const { binding, owner } = this.#requireBinding(token, options, resolutionStack, singleCriterion ?? null);
 
     // A singleton owned by a parent resolver is resolved there, so the parent caches it.
     if (binding.scope === "singleton" && owner !== this) {
@@ -734,20 +721,26 @@ export class DependencyResolver implements ResolverCallbacks {
       return this.resolveAll(dep.token, options, resolutionStack);
     }
     if (dep.optional) {
-      return this.resolveOptional(dep.token, options, resolutionStack);
+      return this.resolveOptional(dep.token, options, resolutionStack, singleCriterionForSlot(dep));
     }
     if (options === undefined) {
       return this.resolveFromContext(dep.token, resolutionStack);
     }
-    return this.resolve(dep.token, options, resolutionStack);
+    return this.resolve(dep.token, options, resolutionStack, singleCriterionForSlot(dep));
   }
 
   resolveOptional<Value>(
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
     resolutionStack: Array<ResolutionFrame>,
+    precomputedCriterion?: BindingTag | null,
   ): Value | undefined {
-    const entry = this.#findBinding(token, options, resolutionStack);
+    const entry = this.#findBinding(
+      token,
+      options,
+      resolutionStack,
+      precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined),
+    );
     if (entry === undefined) {
       return undefined;
     }
@@ -860,13 +853,24 @@ export class DependencyResolver implements ResolverCallbacks {
     return this.#resolveBindingAsync(binding, undefined, resolutionStack, branchDepth, owner);
   }
 
+  /**
+   * Instantiates one owned binding directly, bypassing selection.
+   *
+   * @remarks Warm-up must build the binding it inspected: re-selecting by the slot's own criteria
+   * could pick a different candidate whose criteria are a subset of them.
+   */
+  warmBindingAsync(binding: Binding, options: ResolveOptions | undefined): Promise<unknown> {
+    return this.#resolveBindingAsync(binding, options, [], ROOT_BRANCH, this);
+  }
+
   async resolveAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
     resolutionStack: Array<ResolutionFrame>,
     branchDepth: BranchDepth = UNOWNED_BRANCH,
+    precomputedCriterion?: BindingTag | null,
   ): Promise<Value> {
-    const { binding, owner } = this.#requireBinding(token, options, resolutionStack);
+    const { binding, owner } = this.#requireBinding(token, options, resolutionStack, precomputedCriterion);
 
     if (binding.scope === "singleton" && owner !== this) {
       return owner.#resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner) as Promise<Value>;
@@ -1105,12 +1109,12 @@ export class DependencyResolver implements ResolverCallbacks {
       return this.resolveAllAsync(dep.token, options, resolutionStack, branchDepth);
     }
     if (dep.optional) {
-      return this.resolveOptionalAsync(dep.token, options, resolutionStack, branchDepth);
+      return this.resolveOptionalAsync(dep.token, options, resolutionStack, branchDepth, singleCriterionForSlot(dep));
     }
     if (options === undefined) {
       return this.resolveAsyncFromContext(dep.token, resolutionStack, branchDepth);
     }
-    return this.resolveAsync(dep.token, options, resolutionStack, branchDepth);
+    return this.resolveAsync(dep.token, options, resolutionStack, branchDepth, singleCriterionForSlot(dep));
   }
 
   async resolveOptionalAsync<Value>(
@@ -1118,8 +1122,14 @@ export class DependencyResolver implements ResolverCallbacks {
     options: ResolveOptions | undefined,
     resolutionStack: Array<ResolutionFrame>,
     branchDepth: BranchDepth = UNOWNED_BRANCH,
+    precomputedCriterion?: BindingTag | null,
   ): Promise<Value | undefined> {
-    const entry = this.#findBinding(token, options, resolutionStack);
+    const entry = this.#findBinding(
+      token,
+      options,
+      resolutionStack,
+      precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined),
+    );
     if (entry === undefined) {
       return undefined;
     }
@@ -1170,29 +1180,11 @@ export class DependencyResolver implements ResolverCallbacks {
     return result;
   }
 
-  /** Every binding the chain's name indexes hold for one name, nearest container first. */
-  #namedBindingsFromChain(token: Token<unknown> | Constructor, name: string): Array<Binding> {
-    // A name resolves to at most one binding per registry, so a root container's answer is built
-    // whole rather than grown — the list is sized at its allocation.
-    const ownBinding = this.#registry.getSimpleNamed(token, name);
-    if (this.#parent === undefined) {
-      return ownBinding === undefined ? [] : [ownBinding];
-    }
-    const result: Array<Binding> = ownBinding === undefined ? [] : [ownBinding];
-    for (let current: DependencyResolver | undefined = this.#parent; current !== undefined; current = current.#parent) {
-      const binding = current.#registry.getSimpleNamed(token, name);
-      if (binding !== undefined) {
-        result.push(binding);
-      }
-    }
-    return result;
-  }
-
   /**
-   * The candidates an index can name outright, or `null` when the request needs full selection.
+   * The candidates the index can name outright, or `null` when the request needs full selection.
    *
-   * @remarks Kept off `#candidateBindings` so that method stays the size it was: a request neither
-   * index serves must not pay for the two that do.
+   * @remarks Kept off `#candidateBindings` so that method stays the size it was: a request the
+   * index cannot serve must not pay for the shape it does.
    * An index has matched the slot already, but a hit may still carry a predicate, and evaluating
    * that is the selection path's job.
    */
@@ -1201,31 +1193,26 @@ export class DependencyResolver implements ResolverCallbacks {
     options: ResolveOptions,
     resolutionStack: Array<ResolutionFrame>,
   ): ReadonlyArray<Binding> | null {
-    if (isNameOnlyOptions(options)) {
-      const named = this.#namedBindingsFromChain(token, options.name);
-      return anyPredicate(named)
-        ? selectAllBindings(named, options, this.#makeConstraintContext(resolutionStack, options))
-        : named;
-    }
-    const singleTag = singleTagOnlyOf(options);
-    if (singleTag === undefined) {
+    const singleCriterion = singleCriterionOnlyOf(options);
+    if (singleCriterion === undefined) {
       return null;
     }
-    const tagged = this.#taggedBindingsFromChain(token, singleTag);
-    return anyPredicate(tagged)
-      ? selectAllBindings(tagged, options, this.#makeConstraintContext(resolutionStack, options))
-      : tagged;
+    const indexed = this.#taggedBindingsFromChain(token, singleCriterion);
+    return anyPredicate(indexed)
+      ? selectAllBindings(indexed, options, this.#makeConstraintContext(resolutionStack, options))
+      : indexed;
   }
 
   /**
-   * Every binding the chain's tag indexes hold for one tag, nearest container first.
+   * Every binding the chain's criterion indexes hold for one criterion, nearest container first.
    *
-   * @remarks A request for one tag and no name matches exactly the bindings the index keys, so this
-   * is the whole candidate set rather than a prefilter — a named or multi-tag slot cannot satisfy it.
+   * @remarks A request for exactly one criterion matches exactly the bindings the index keys, so
+   * this is the whole candidate set rather than a prefilter — a multi-criterion slot cannot satisfy
+   * it.
    */
   #taggedBindingsFromChain(token: Token<unknown> | Constructor, tag: BindingTag): Array<Binding> {
-    // A tag matches at most one binding per registry, so a root container's answer is built whole
-    // rather than grown — the shape `#namedBindingsFromChain` takes, for the same reason.
+    // A criterion matches at most one binding per registry, so a root container's answer is built
+    // whole rather than grown — the list is sized at its allocation.
     const ownBinding = this.#registry.getSimpleTagged(token, tag);
     if (this.#parent === undefined) {
       return ownBinding === undefined ? [] : [ownBinding];
@@ -1282,18 +1269,23 @@ export class DependencyResolver implements ResolverCallbacks {
     return buildConstraintContext(resolutionStack, options);
   }
 
-  /** Selection for a name-less multi-tag request, over the union of the two tag indexes. */
+  /** Selection for a multi-criterion request, over the union of the two tag indexes. */
   #selectMultiTagged(
     token: Token<unknown> | Constructor,
     options: ResolveOptions,
     resolutionStack: Array<ResolutionFrame>,
   ): Binding | undefined {
     const candidates: Array<Binding> = [];
-    this.#gatherTagCandidates(token, options.tag, candidates);
+    const gathered: Array<BindingTag> = [];
+    if (options.name !== undefined) {
+      // Read, not minted: an unminted name has no criterion, so no slot can carry it.
+      this.#gatherTagCandidates(token, slotNameCriterionOf(options.name), candidates, gathered);
+    }
+    this.#gatherTagCandidates(token, options.tag, candidates, gathered);
     const listed = options.tags;
     if (listed !== undefined) {
       for (let index = 0; index < listed.length; index += 1) {
-        this.#gatherTagCandidates(token, listed[index], candidates);
+        this.#gatherTagCandidates(token, listed[index], candidates, gathered);
       }
     }
     if (candidates.length === 0) {
@@ -1307,37 +1299,26 @@ export class DependencyResolver implements ResolverCallbacks {
     token: Token<unknown> | Constructor,
     criterion: BindingTag | undefined,
     out: Array<Binding>,
+    gathered: Array<BindingTag>,
   ): void {
-    if (criterion === undefined) {
+    // Distinct criteria never share a binding — a slot lives in exactly one bucket — so deduping
+    // by criterion covers a request repeating one across its spellings, without scanning `out`.
+    if (criterion === undefined || gathered.includes(criterion)) {
       return;
     }
-    // The includes probes only guard a request repeating a criterion across its two spellings.
+    gathered.push(criterion);
     const single = this.#registry.getSimpleTagged(token, criterion);
-    if (single !== undefined && !out.includes(single)) {
+    if (single !== undefined) {
       out.push(single);
     }
     const bucket = this.#registry.getMultiTagged(token, criterion);
     if (bucket !== undefined) {
       for (let index = 0; index < bucket.length; index += 1) {
-        const candidate = bucket[index]!;
-        if (!out.includes(candidate)) {
-          out.push(candidate);
-        }
+        out.push(bucket[index]!);
       }
     }
   }
 
-  #matchesBindingFast(
-    binding: Binding,
-    options: ResolveOptions | undefined,
-    resolutionStack: Array<ResolutionFrame>,
-  ): boolean {
-    if (!matchesSlot(binding.slot, options)) {
-      return false;
-    }
-    return this.#satisfiesPredicate(binding, options, resolutionStack);
-  }
-
   /** The predicate half of a match, for a lane whose index has already settled the slot. */
   #satisfiesPredicate(
     binding: Binding,

package/src/resolution/select/binding-select.ts

@@ -1,6 +1,6 @@
 import type { Binding, BindingSlot } from "#/core/binding";
 import type { BindingTag, TagKeyMask } from "#/core/tag";
-import { coversTagKeys, NO_TAG_KEYS } from "#/core/tag";
+import { coversTagKeys, NO_TAG_KEYS, slotName, slotNameCriterionOf } from "#/core/tag";
 import type { ConstraintContext, ResolveOptions } from "#/core/types";
 import { AmbiguousBindingError } from "#/errors/errors";
 
@@ -41,7 +41,7 @@ export function selectBinding(
   }
   // Reached only where the throw was: a slot declaring more of what the request carries is the more
   // specific match, so an over-specified request resolves instead of being ambiguous.
-  const mostSpecific = mostSpecificByTagCount(candidates);
+  const mostSpecific = mostSpecificByCriterionCount(candidates);
   if (mostSpecific !== undefined) {
     return mostSpecific;
   }
@@ -51,8 +51,8 @@ export function selectBinding(
   );
 }
 
-/** The lone candidate declaring more tags than every other, or `undefined` when that is a tie. */
-function mostSpecificByTagCount(candidates: ReadonlyArray<Binding>): Binding | undefined {
+/** The lone candidate declaring more criteria than every other, or `undefined` when that is a tie. */
+function mostSpecificByCriterionCount(candidates: ReadonlyArray<Binding>): Binding | undefined {
   let best: Binding | undefined;
   let bestCount = -1;
   let tied = false;
@@ -118,35 +118,24 @@ function filterBindings(
 }
 
 function hasSlotCriterion(options: ResolveOptions): boolean {
-  return options.name !== undefined || requestedTagKeyMask(options) !== NO_TAG_KEYS;
+  return requestedTagKeyMask(options) !== NO_TAG_KEYS;
 }
 
 /**
- * Whether a binding's slot satisfies a request: names must be equal, and every tag the slot
- * declares must be among the tags requested.
+ * Whether a binding's slot satisfies a request: every criterion the slot declares must be among
+ * the request's criteria, a name spelling either side folding to the reserved criterion.
  *
- * @remarks The tag half is a key-mask subset test before any criterion is read, so a slot the
- * request cannot satisfy is rejected in one word compare. Criteria are interned, so what follows is
- * identity.
+ * @remarks A key-mask subset test runs before any criterion is read, so a slot the request cannot
+ * satisfy is rejected in one word compare. Criteria are interned, so what follows is identity.
  *
  * @since 0.5.0-canary.9
  */
 export function matchesSlot(slot: BindingSlot, options: ResolveOptions | undefined): boolean {
-  const requestedName = options?.name;
-
-  if (slot.name !== undefined) {
-    if (slot.name !== requestedName) {
-      return false;
-    }
-  } else if (requestedName !== undefined) {
-    return false;
-  }
-
   const slotMask = slot.keyMask;
   const requestMask = requestedTagKeyMask(options);
 
   if (slotMask === NO_TAG_KEYS) {
-    // A request carrying tags needs a tagged slot: an untagged binding never matches.
+    // A request carrying any criterion never falls back to the default slot.
     return requestMask === NO_TAG_KEYS;
   }
   if (!coversTagKeys(requestMask, slotMask)) {
@@ -178,6 +167,9 @@ export function requestedTagKeyMask(options: ResolveOptions | undefined): TagKey
   const listed = options.tags;
   let mask = single === undefined ? NO_TAG_KEYS : single.mask;
 
+  if (options.name !== undefined) {
+    mask = (mask | slotName.mask) as TagKeyMask;
+  }
   if (listed !== undefined) {
     for (let index = 0; index < listed.length; index += 1) {
       mask = (mask | listed[index]!.mask) as TagKeyMask;
@@ -192,6 +184,11 @@ function requestCarries(options: ResolveOptions | undefined, criterion: BindingT
   if (options === undefined) {
     return false;
   }
+  // The `name` spelling folds through the intern read, so this too is identity — a hand-built
+  // criterion matches nothing on any lane, and an unminted name retains nothing.
+  if (criterion.key === slotName && options.name !== undefined && criterion === slotNameCriterionOf(options.name)) {
+    return true;
+  }
   if (options.tag === criterion) {
     return true;
   }

package/src/resolution/select/constraints.ts

@@ -7,6 +7,8 @@ import type { BindingConstraint, Constructor } from "#/core/types";
 import { EmptyTagCriteriaError } from "#/errors/errors";
 
 /**
+ * Matches when the direct parent frame resolves the given token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenParentIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -16,6 +18,8 @@ export function whenParentIs(token: Token<unknown> | Constructor): BindingConstr
 }
 
 /**
+ * Matches when there is no direct parent frame, or it resolves a different token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenNoParentIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -25,6 +29,8 @@ export function whenNoParentIs(token: Token<unknown> | Constructor): BindingCons
 }
 
 /**
+ * Matches when at least one ancestor frame resolves the given token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -34,6 +40,8 @@ export function whenAnyAncestorIs(token: Token<unknown> | Constructor): BindingC
 }
 
 /**
+ * Matches when no ancestor frame resolves the given token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenNoAncestorIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -43,6 +51,8 @@ export function whenNoAncestorIs(token: Token<unknown> | Constructor): BindingCo
 }
 
 /**
+ * Matches when the direct parent slot carries the given name.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenParentNamed(name: string): BindingConstraint {
@@ -54,6 +64,8 @@ export function whenParentNamed(name: string): BindingConstraint {
 }
 
 /**
+ * Matches when at least one ancestor slot carries the given name.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorNamed(name: string): BindingConstraint {
@@ -65,6 +77,8 @@ export function whenAnyAncestorNamed(name: string): BindingConstraint {
 }
 
 /**
+ * Matches when the direct parent slot carries the given tag pair.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenParentTagged(criterion: BindingTag): BindingConstraint {
@@ -73,6 +87,8 @@ export function whenParentTagged(criterion: BindingTag): BindingConstraint {
 }
 
 /**
+ * Matches when at least one ancestor slot carries the given tag pair.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorTagged(criterion: BindingTag): BindingConstraint {