@codefast/di 0.11.0 → 0.12.0

package/dist/decorators/inject.js

@@ -1,9 +1,9 @@
-import { getActiveContainer, getAmbientResolution } from "#ambient/active-container";
-import { decoratorMetadataOf } from "#decorators/decorator-metadata";
-import { MissingContainerContextError, StaticMemberDecoratorError } from "#errors/errors";
+import { getActiveContainer, getAmbientResolution } from "#ambient-container";
+import { decoratorMetadataOf } from "#decorators/metadata-record";
+import { MissingContainerContextError, StaticMemberDecoratorError } from "#errors";
+import { injectionSlotToResolveOptions } from "#injection/dependency-slot";
 import { buildInjectionDescriptor } from "#injection/descriptor";
-import { injectionSlotToResolveOptions } from "#injection/resolve-options";
-import { INJECT_ACCESSOR_KEY } from "#metadata/metadata-keys";
+import { INJECT_ACCESSOR_KEY } from "#metadata/keys";
 /**
  * The name of the class being constructed, or `undefined` when there is none to report.
  *

package/dist/decorators/injectable.js

@@ -1,6 +1,6 @@
-import { decoratorMetadataOf } from "#decorators/decorator-metadata";
+import { decoratorMetadataOf } from "#decorators/metadata-record";
 import { normalizeToDescriptor } from "#injection/descriptor";
-import { INJECTABLE_KEY } from "#metadata/metadata-keys";
+import { INJECTABLE_KEY } from "#metadata/keys";
 /**
  * Creates an empty auto-register registry.
  *

package/dist/decorators/{lifecycle-decorators.js → lifecycle.js}

@@ -1,6 +1,6 @@
-import { decoratorMetadataOf } from "#decorators/decorator-metadata";
-import { StaticMemberDecoratorError, SymbolKeyedLifecycleError } from "#errors/errors";
-import { LIFECYCLE_KEY } from "#metadata/metadata-keys";
+import { decoratorMetadataOf } from "#decorators/metadata-record";
+import { StaticMemberDecoratorError, SymbolKeyedLifecycleError } from "#errors";
+import { LIFECYCLE_KEY } from "#metadata/keys";
 /** Records the decorated method under one lifecycle phase; both decorators differ only in that phase. */
 function recordLifecycleMethod(phase) {
     return function (target, context) {

package/dist/decorators/{decorator-metadata.js → metadata-record.js}

@@ -1,7 +1,7 @@
 /**
  * The metadata record a decorator writes into, checked once for every decorator the library ships.
  */
-import { MissingDecoratorMetadataError } from "#errors/errors";
+import { MissingDecoratorMetadataError } from "#errors";
 /**
  * Returns the metadata record a decorator context carries.
  *

package/dist/{errors/errors.d.ts → errors.d.ts}

@@ -246,10 +246,11 @@ export declare class MissingContainerContextError extends DiError {
     constructor(className: string | undefined, accessorName: string | symbol);
 }
 /**
- * A second `to*()` on a chain that already registered its binding.
+ * A slot step or a second `to*()` on a chain that already registered its binding.
  *
- * @remarks A chain is its binding, so it registers exactly once; a token bound twice is two `bind()`
- * calls, the second of which displaces the first under slot last-wins.
+ * @remarks A chain is its binding and registers exactly once, in its final shape, so its slot is
+ * settled by `to*()`; a token bound twice is two `bind()` calls, the second of which displaces the
+ * first under slot last-wins.
  *
  * @since 0.10.0
  */
@@ -274,11 +275,11 @@ export declare class ManyBindingSlotError extends DiError {
     constructor(tokenName: string);
 }
 /**
- * A fluent chain was refined before a `to*()` call gave it a binding to refine.
+ * A scope, a lifecycle hook or `id()` asked of a fluent chain before a `to*()` call registered its binding.
  *
  * @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.
+ * `BindToBuilder`, which exposes only the slot steps and `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.10.0
  */

package/dist/{errors/errors.js → errors.js}

@@ -337,10 +337,11 @@ export class MissingContainerContextError extends DiError {
     }
 }
 /**
- * A second `to*()` on a chain that already registered its binding.
+ * A slot step or a second `to*()` on a chain that already registered its binding.
  *
- * @remarks A chain is its binding, so it registers exactly once; a token bound twice is two `bind()`
- * calls, the second of which displaces the first under slot last-wins.
+ * @remarks A chain is its binding and registers exactly once, in its final shape, so its slot is
+ * settled by `to*()`; a token bound twice is two `bind()` calls, the second of which displaces the
+ * first under slot last-wins.
  *
  * @since 0.10.0
  */
@@ -349,7 +350,7 @@ export class ChainAlreadyRegisteredError extends DiError {
     code = "CHAIN_ALREADY_REGISTERED";
     tokenName;
     constructor(tokenName) {
-        super(`The binding for token '${tokenName}' is already registered on this chain. Call bind() again to register another binding for the token.`);
+        super(`The binding for token '${tokenName}' is already registered on this chain, so its slot is final. Declare when*() and many() before to*(), or call bind() again to register another binding for the token.`);
         this.tokenName = tokenName;
     }
 }
@@ -371,11 +372,11 @@ export class ManyBindingSlotError extends DiError {
     }
 }
 /**
- * A fluent chain was refined before a `to*()` call gave it a binding to refine.
+ * A scope, a lifecycle hook or `id()` asked of a fluent chain before a `to*()` call registered its binding.
  *
  * @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.
+ * `BindToBuilder`, which exposes only the slot steps and `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.10.0
  */

package/dist/index.d.ts

@@ -3,13 +3,15 @@ export { token, tokenName } from "#core/token";
 export type { SlotNamesOf, Token } from "#core/token";
 export { coversTagKeys, NO_TAG_KEYS, slotName, tag, tagKeyMaskOf } from "#core/tag";
 export type { TagKey, TagKeyMask } from "#core/tag";
-export type { AliasBindingBuilder, BindToBuilder, BindingBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, SlotConstrainedBuilder, TransientBindingBuilder, } from "#core/binding";
+export type { AliasBindingBuilder, BindToBuilder, BindingBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, SlotConstrainedBuilder, TransientBindingBuilder, } from "#core/binding-builders";
 export { Container } from "#container/container";
 export type { Container as ContainerInterface, ContainerOptions, ContainerStatic } from "#container/container";
-export { getActiveContainer, runWithContainer } from "#ambient/active-container";
-export { bindingSlotToResolveOptions, injectionSlotToResolveOptions, resolveOptionsForSlot, } from "#injection/resolve-options";
-export type { DependencySlot } from "#injection/resolve-options";
+export { getActiveContainer, runWithContainer } from "#ambient-container";
+export { bindingSlotToResolveOptions, injectionSlotToResolveOptions, resolveOptionsForSlot, } from "#injection/dependency-slot";
+export type { DependencySlot } from "#injection/dependency-slot";
 export type { BindingSnapshot, ContainerSnapshot } from "#introspection/inspector";
+export type { CandidateExplanation, CandidateVerdict, ExplainOptions, ExplanationOutcome, ExplanationStep, ResolutionExplanation, SelectionRule, } from "#introspection/explanation";
+export type { CandidateRule } from "#resolution/select/candidates";
 export type { ContainerGraphJson, GraphEdge, GraphNode, GraphOptions } from "#introspection/dependency-graph";
 export { AsyncModule, isSyncModule, Module, SyncModule } from "#core/module";
 export type { AsyncModuleBuilder, ModuleBuilder } from "#core/module";
@@ -20,15 +22,15 @@ export { injectAll, isInjectionDescriptor, optional } from "#injection/descripto
 export type { InjectionDescriptor, InjectOptions } from "#injection/descriptor";
 export { injectable } from "#decorators/injectable";
 export type { InjectableDependency, InjectableOptions } from "#decorators/injectable";
-export { postConstruct, preDestroy } from "#decorators/lifecycle-decorators";
+export { postConstruct, preDestroy } from "#decorators/lifecycle";
 export { createAutoRegisterRegistry } from "#decorators/injectable";
 export type { AutoRegisterRegistry } from "#decorators/injectable";
-export { MetadataReaderToken } from "#metadata/metadata-reader-token";
-export type { ConstructorMetadata, LifecycleMetadata, MetadataReader, MutableLifecycleMetadata, ParamMetadata, } from "#metadata/metadata-types";
-export { defaultMetadataReader, SymbolMetadataReader } from "#metadata/symbol-metadata-reader";
+export { MetadataReaderToken } from "#metadata/reader-token";
+export type { ConstructorMetadata, LifecycleMetadata, MetadataReader, MutableLifecycleMetadata, ParamMetadata, } from "#metadata/types";
+export { defaultMetadataReader, SymbolMetadataReader } from "#metadata/symbol-reader";
 export { whenAnyAncestorIs, whenAnyAncestorNamed, whenAnyAncestorTagged, whenAnyAncestorTaggedAll, whenNoAncestorIs, whenNoParentIs, whenParentIs, whenParentNamed, whenParentTagged, whenParentTaggedAll, } from "#resolution/select/constraints";
-export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors/errors";
-export type { ScopeViolationDetails } from "#errors/errors";
+export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
+export type { ScopeViolationDetails } from "#errors";
 export { toDotGraph } from "#introspection/graph-adapters/dot";
 export { toCytoscapeGraph } from "#introspection/graph-adapters/cytoscape";
 export type { CytoscapeEdge, CytoscapeElements, CytoscapeNode } from "#introspection/graph-adapters/cytoscape";

package/dist/index.js

@@ -6,10 +6,10 @@ export { coversTagKeys, NO_TAG_KEYS, slotName, tag, tagKeyMaskOf } from "#core/t
 export { Container } from "#container/container";
 // Ambient container — the context an `@inject` accessor initializer resolves from. `resolution/context`
 // stays internal: it hands out resolver callbacks, not public values.
-export { getActiveContainer, runWithContainer } from "#ambient/active-container";
+export { getActiveContainer, runWithContainer } from "#ambient-container";
 // `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 { bindingSlotToResolveOptions, injectionSlotToResolveOptions, resolveOptionsForSlot, } from "#injection/resolve-options";
+export { bindingSlotToResolveOptions, injectionSlotToResolveOptions, resolveOptionsForSlot, } from "#injection/dependency-slot";
 // Module
 export { AsyncModule, isSyncModule, Module, SyncModule } from "#core/module";
 export { binding } from "#core/binding-declaration";
@@ -17,16 +17,16 @@ export { binding } from "#core/binding-declaration";
 export { inject } from "#decorators/inject";
 export { injectAll, isInjectionDescriptor, optional } from "#injection/descriptor";
 export { injectable } from "#decorators/injectable";
-export { postConstruct, preDestroy } from "#decorators/lifecycle-decorators";
+export { postConstruct, preDestroy } from "#decorators/lifecycle";
 // Auto-register
 export { createAutoRegisterRegistry } from "#decorators/injectable";
 // MetadataReader — everything a consumer needs to write one and pass it to Container.create()
-export { MetadataReaderToken } from "#metadata/metadata-reader-token";
-export { defaultMetadataReader, SymbolMetadataReader } from "#metadata/symbol-metadata-reader";
+export { MetadataReaderToken } from "#metadata/reader-token";
+export { defaultMetadataReader, SymbolMetadataReader } from "#metadata/symbol-reader";
 // Constraints — contextual injection predicates for .when()
 export { whenAnyAncestorIs, whenAnyAncestorNamed, whenAnyAncestorTagged, whenAnyAncestorTaggedAll, whenNoAncestorIs, whenNoParentIs, whenParentIs, whenParentNamed, whenParentTagged, whenParentTaggedAll, } from "#resolution/select/constraints";
 // Errors
-export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors/errors";
+export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
 // Graph adapters — render `generateDependencyGraph()` output for common viewers
 export { toDotGraph } from "#introspection/graph-adapters/dot";
 export { toCytoscapeGraph } from "#introspection/graph-adapters/cytoscape";

package/dist/injection/descriptor.d.ts

@@ -1,7 +1,7 @@
 /** The one shape every declared dependency is normalised to, whatever channel declared it. */
 import type { Token } from "#core/token";
 import type { BindingTag, Constructor, TokenValue } from "#core/types";
-import type { DependencySlot } from "#injection/resolve-options";
+import type { DependencySlot } from "#injection/dependency-slot";
 /**
  * Slot-selection options — a name and tags — a declared dependency narrows its binding with.
  *

package/dist/introspection/dependency-graph.d.ts

@@ -1,6 +1,6 @@
 import type { BindingRegistry } from "#core/registry";
 import type { BindingKind, BindingScope } from "#core/types";
-import type { MetadataReader } from "#metadata/metadata-types";
+import type { MetadataReader } from "#metadata/types";
 /**
  * @remarks `kind`/`scope` are `"unbound"` for the placeholder node an optional, currently
  * unsatisfied dependency points at.

package/dist/introspection/dependency-graph.js

@@ -1,9 +1,8 @@
-import { stringifyTagValue } from "#core/binding";
-import { effectiveBindingScope } from "#core/binding-scope";
+import { effectiveBindingScope, stringifyTagValue } from "#core/binding";
 import { slotName } from "#core/tag";
 import { tokenName } from "#core/token";
-import { bindingSlotToResolveOptions } from "#injection/resolve-options";
-import { matchesSlot } from "#resolution/select/binding-select";
+import { bindingSlotToResolveOptions } from "#injection/dependency-slot";
+import { matchesSlot } from "#resolution/select/candidates";
 // ── Builder ──────────────────────────────────────────────────────────────────────────────────────────────────────────
 // Tokens are compared by object identity, and a name is free to repeat, so the graph mints its
 // own per-process key. Weakly held: a discarded token takes its key with it.

package/dist/introspection/explanation.d.ts

@@ -0,0 +1,101 @@
+import type { BindingRegistry } from "#core/registry";
+import type { Token } from "#core/token";
+import type { Constructor, ResolveOptions } from "#core/types";
+import type { BindingSnapshot } from "#introspection/inspector";
+import type { CandidateRule } from "#resolution/select/candidates";
+/**
+ * A request to explain: the criteria a `resolve` would carry, and the resolutions it is nested in.
+ *
+ * @typeParam Names - the slot names the token declares, as `ResolveOptions` narrows them
+ *
+ * @since 0.12.0
+ */
+export interface ExplainOptions<Names extends string = string> extends ResolveOptions<Names> {
+    /**
+     * The tokens whose resolution makes this request, outermost first, so a `when()` predicate reads the parent
+     * and ancestors it would read inside their factories.
+     *
+     * @remarks Each is selected as a request with no criteria, nested in the ones before it; one that selects
+     * nothing throws what its own `resolve` would.
+     */
+    readonly ancestors?: ReadonlyArray<Token<unknown> | Constructor> | undefined;
+}
+/**
+ * What selection made of one binding: in the running, or out and why.
+ *
+ * @remarks `slot-mismatch`: the slot declares a criterion the request does not carry, or the request carries
+ * criteria and the slot is the default one. `predicate-refused`: the slot matched and the `when()` predicate
+ * returned `false`. `collection-member`: a `many()` binding, which only `resolveAll` takes.
+ *
+ * @since 0.12.0
+ */
+export type CandidateVerdict = "eligible" | "slot-mismatch" | "predicate-refused" | "collection-member";
+/**
+ * The rule that settled one registry's answer.
+ *
+ * @remarks The four candidate rules of `CandidateRule`, plus `default-alias`: no slot matched, and the token's
+ * default-slot alias forwards the request's criteria to its target.
+ *
+ * @since 0.12.0
+ */
+export type SelectionRule = CandidateRule | "default-alias";
+/**
+ * How an explained lookup ended, one outcome for each way `resolve` ends.
+ *
+ * @remarks `unbound` and `unmatched` are the lookups `resolve` reports as `TokenNotBoundError` and
+ * `NoMatchingBindingError`; `ambiguous` and `alias-cycle` are `AmbiguousBindingError` and `CircularDependencyError`.
+ *
+ * @since 0.12.0
+ */
+export type ExplanationOutcome = "selected" | "unbound" | "unmatched" | "ambiguous" | "alias-cycle";
+/**
+ * One binding a registry offered the request, and what selection made of it.
+ *
+ * @since 0.12.0
+ */
+export interface CandidateExplanation {
+    readonly binding: BindingSnapshot;
+    readonly verdict: CandidateVerdict;
+}
+/**
+ * One registry the lookup read, in the order `resolve` reads them.
+ *
+ * @since 0.12.0
+ */
+export interface ExplanationStep {
+    /** The token looked up here, which an alias hop changes. */
+    readonly tokenName: string;
+    /** How far up the chain the registry sits: `0` is the container asked, `1` its parent. */
+    readonly depth: number;
+    /** Every binding this registry holds for the token, in registration order. */
+    readonly candidates: ReadonlyArray<CandidateExplanation>;
+    /** The rule that settled this registry's answer, or `undefined` when no candidate was eligible. */
+    readonly rule: SelectionRule | undefined;
+    /** The binding this registry answered with, an alias included, or `undefined` when the lookup moved on. */
+    readonly selected: BindingSnapshot | undefined;
+}
+/**
+ * Why one request selects the binding it does, or why it selects none.
+ *
+ * @since 0.12.0
+ */
+export interface ResolutionExplanation {
+    /** The token the request asks for. */
+    readonly tokenName: string;
+    /** Every registry that holds a token the lookup asked for, once per alias hop, in the order it read them. */
+    readonly steps: ReadonlyArray<ExplanationStep>;
+    /** The binding the request resolves to after every alias, or `undefined` when it resolves to none. */
+    readonly selected: BindingSnapshot | undefined;
+    readonly outcome: ExplanationOutcome;
+}
+/**
+ * Explains a request against a container chain, without instantiating anything.
+ *
+ * @param registries - the asked container's registry first, then each ancestor's up to the root
+ * @param token - the token the request asks for
+ * @param options - the request's criteria and the resolutions it is nested in
+ * @throws An error `resolve` would throw, when one of `options.ancestors` selects no binding
+ *
+ * @since 0.12.0
+ */
+export declare function explainRequest(registries: ReadonlyArray<BindingRegistry>, token: Token<unknown> | Constructor, options: ExplainOptions | undefined): ResolutionExplanation;

package/dist/introspection/explanation.js

@@ -0,0 +1,151 @@
+import { bindingSlotToString } from "#core/binding";
+import { tokenName } from "#core/token";
+import { AmbiguousBindingError, CircularDependencyError, InternalError, NoMatchingBindingError, TokenNotBoundError, } from "#errors";
+import { snapshotOf } from "#introspection/inspector";
+import { DefaultConstraintContext } from "#resolution/context";
+import { buildResolutionFrame } from "#resolution/path";
+import { candidateRuleOf, chooseCandidate, matchesSlot } from "#resolution/select/candidates";
+// ── Explanation ──────────────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Explains a request against a container chain, without instantiating anything.
+ *
+ * @param registries - the asked container's registry first, then each ancestor's up to the root
+ * @param token - the token the request asks for
+ * @param options - the request's criteria and the resolutions it is nested in
+ * @throws An error `resolve` would throw, when one of `options.ancestors` selects no binding
+ *
+ * @since 0.12.0
+ */
+export function explainRequest(registries, token, options) {
+    const stack = [];
+    for (const ancestor of options?.ancestors ?? []) {
+        const walk = walkLookup(registries, ancestor, undefined, stack);
+        if (walk.binding === undefined) {
+            throw lookupError(registries, walk);
+        }
+        stack.push(buildResolutionFrame(walk.binding, tokenName(walk.binding.token)));
+    }
+    const walk = walkLookup(registries, token, requestOf(options), stack);
+    return {
+        tokenName: tokenName(token),
+        steps: walk.steps,
+        selected: walk.binding === undefined ? undefined : snapshotOf(walk.binding),
+        outcome: walk.outcome,
+    };
+}
+// The `ancestors` key is explain's own, and a request carrying no criterion is the request with no options.
+function requestOf(options) {
+    if (options === undefined ||
+        (options.name === undefined && options.tag === undefined && options.tags === undefined)) {
+        return undefined;
+    }
+    const { ancestors: _ancestors, ...request } = options;
+    return request;
+}
+function walkLookup(registries, token, request, stack) {
+    const ctx = new DefaultConstraintContext(stack, request);
+    const steps = [];
+    let current = token;
+    let visited;
+    for (;;) {
+        const found = findInChain(registries, current, request, ctx, steps);
+        if (found.kind === "tie") {
+            return {
+                steps,
+                binding: undefined,
+                outcome: "ambiguous",
+                lastToken: current,
+                ambiguity: found.eligible,
+                cycle: undefined,
+            };
+        }
+        if (found.kind === "none") {
+            const outcome = registries.some((registry) => registry.getAll(current).length > 0) ? "unmatched" : "unbound";
+            return { steps, binding: undefined, outcome, lastToken: current, ambiguity: undefined, cycle: undefined };
+        }
+        const binding = found.binding;
+        if (binding.kind !== "alias") {
+            return { steps, binding, outcome: "selected", lastToken: current, ambiguity: undefined, cycle: undefined };
+        }
+        // An alias hop restarts at the container asked, as `resolve` does, and a revisited token is a cycle.
+        const target = binding.target;
+        visited ??= new Set([current]);
+        if (visited.has(target)) {
+            return {
+                steps,
+                binding: undefined,
+                outcome: "alias-cycle",
+                lastToken: current,
+                ambiguity: undefined,
+                cycle: [...visited, target],
+            };
+        }
+        visited.add(target);
+        current = target;
+    }
+}
+const NO_ANSWER = { kind: "none" };
+function findInChain(registries, token, request, ctx, steps) {
+    for (let depth = 0; depth < registries.length; depth += 1) {
+        const registry = registries[depth];
+        const bindings = registry.getAll(token);
+        if (bindings.length === 0) {
+            continue;
+        }
+        const candidates = [];
+        const eligible = [];
+        for (const binding of bindings) {
+            const verdict = verdictOf(binding, request, ctx);
+            candidates.push({ binding: snapshotOf(binding), verdict });
+            if (verdict === "eligible") {
+                eligible.push(binding);
+            }
+        }
+        const name = tokenName(token);
+        if (eligible.length > 0) {
+            const selected = chooseCandidate(eligible);
+            steps.push({
+                tokenName: name,
+                depth,
+                candidates,
+                rule: candidateRuleOf(eligible, selected),
+                selected: selected === undefined ? undefined : snapshotOf(selected),
+            });
+            return selected === undefined ? { kind: "tie", eligible } : { kind: "binding", binding: selected };
+        }
+        // A request carrying criteria that no slot here matches is forwarded by the token's default-slot alias.
+        const defaultSlot = request === undefined ? undefined : registry.defaultSlotAlias(token);
+        if (defaultSlot !== undefined) {
+            steps.push({ tokenName: name, depth, candidates, rule: "default-alias", selected: snapshotOf(defaultSlot) });
+            return { kind: "binding", binding: defaultSlot };
+        }
+        steps.push({ tokenName: name, depth, candidates, rule: undefined, selected: undefined });
+    }
+    return NO_ANSWER;
+}
+function verdictOf(binding, request, ctx) {
+    if (binding.isMany) {
+        return "collection-member";
+    }
+    if (!matchesSlot(binding.slot, request)) {
+        return "slot-mismatch";
+    }
+    const predicate = binding.predicate;
+    return predicate === undefined || predicate(ctx) ? "eligible" : "predicate-refused";
+}
+/** The error `resolve` throws for a lookup that ended without a binding. */
+function lookupError(registries, walk) {
+    const name = tokenName(walk.lastToken);
+    switch (walk.outcome) {
+        case "ambiguous":
+            return new AmbiguousBindingError(name, (walk.ambiguity ?? []).map((binding) => binding.identifier));
+        case "alias-cycle":
+            return new CircularDependencyError((walk.cycle ?? []).map((entry) => tokenName(entry)));
+        case "unmatched":
+            return new NoMatchingBindingError(name, {}, registries.flatMap((registry) => registry.getAll(walk.lastToken).map((binding) => bindingSlotToString(binding.slot))));
+        case "unbound":
+            return new TokenNotBoundError(name);
+        case "selected":
+            return new InternalError("a lookup that selected a binding has no error");
+    }
+}

package/dist/introspection/inspector.d.ts

@@ -1,7 +1,8 @@
+import type { Binding } from "#core/binding";
 import type { BindingRegistry } from "#core/registry";
 import type { Token } from "#core/token";
 import type { BindingIdentifier, BindingKind, BindingScope, BindingTag, Constructor, ResolveOptions } from "#core/types";
-import type { ScopeManager } from "#lifecycle/scope-manager";
+import type { ScopeManager } from "#lifecycle/scopes";
 /**
  * A read-only view of one binding: token, kind, scope, slot, and id.
  *
@@ -42,4 +43,10 @@ export declare class Inspector {
     lookupBindings<Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot>;
     /** Whether this container's own registry holds a binding the request could select. */
     hasOwn(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean;
-}
+}
+/**
+ * The public snapshot of one binding, the shape every introspection read reports a binding in.
+ *
+ * @since 0.12.0
+ */
+export declare function snapshotOf(binding: Binding): BindingSnapshot;

package/dist/introspection/inspector.js

@@ -1,7 +1,7 @@
-import { effectiveBindingScope } from "#core/binding-scope";
+import { effectiveBindingScope } from "#core/binding";
 import { tokenName } from "#core/token";
 import { DefaultConstraintContext } from "#resolution/context";
-import { selectAllBindings } from "#resolution/select/binding-select";
+import { selectAllBindings } from "#resolution/select/candidates";
 // ── Inspector ────────────────────────────────────────────────────────────────────────────────────────────────────────
 /**
  * The read-only introspection surface behind a container's `inspect()`.
@@ -21,7 +21,7 @@ export class Inspector {
     }
     inspect() {
         return {
-            ownBindings: this.#registry.allBindings().map((binding) => this.#toSnapshot(binding)),
+            ownBindings: this.#registry.allBindings().map((binding) => snapshotOf(binding)),
             cachedSingletonCount: this.#scope.cachedSingletons().length,
             hasParent: this.#hasParent,
             isDisposed: this.#isDisposed(),
@@ -29,7 +29,7 @@ export class Inspector {
     }
     lookupBindings(token) {
         const bindings = this.#registry.getAll(token);
-        return bindings.map((binding) => this.#toSnapshot(binding));
+        return bindings.map((binding) => snapshotOf(binding));
     }
     /** Whether this container's own registry holds a binding the request could select. */
     hasOwn(token, options) {
@@ -42,24 +42,29 @@ export class Inspector {
         // 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"));
+                this.#registry.defaultSlotAlias(token) !== undefined));
     }
     #makeConstraintContext(options) {
         return new DefaultConstraintContext([], options);
     }
-    #toSnapshot(binding) {
-        // Aliased, not copied: slot tags are frozen where they are built, so a caller's write throws
-        // instead of corrupting the registry — and the snapshot skips an allocation per binding.
-        const slot = binding.slot.name !== undefined
-            ? { name: binding.slot.name, tags: binding.slot.tags }
-            : { tags: binding.slot.tags };
-        return {
-            tokenName: tokenName(binding.token),
-            kind: binding.kind,
-            scope: effectiveBindingScope(binding),
-            slot,
-            id: binding.identifier,
-            isMany: binding.isMany,
-        };
-    }
+}
+/**
+ * The public snapshot of one binding, the shape every introspection read reports a binding in.
+ *
+ * @since 0.12.0
+ */
+export function snapshotOf(binding) {
+    // Aliased, not copied: slot tags are frozen where they are built, so a caller's write throws
+    // instead of corrupting the registry — and the snapshot skips an allocation per binding.
+    const slot = binding.slot.name !== undefined
+        ? { name: binding.slot.name, tags: binding.slot.tags }
+        : { tags: binding.slot.tags };
+    return {
+        tokenName: tokenName(binding.token),
+        kind: binding.kind,
+        scope: effectiveBindingScope(binding),
+        slot,
+        id: binding.identifier,
+        isMany: binding.isMany,
+    };
 }

package/dist/lifecycle/{lifecycle-manager.d.ts → hooks.d.ts}

@@ -1,7 +1,7 @@
 import type { Binding } from "#core/binding";
 import type { Token } from "#core/token";
 import type { ActivationHandler, Constructor, DeactivationHandler, DependencyKey, ResolutionContext } from "#core/types";
-import type { MetadataReader } from "#metadata/metadata-types";
+import type { MetadataReader } from "#metadata/types";
 /**
  * One container's registry of container-level activation and deactivation hooks, keyed by token.
  *
@@ -19,7 +19,14 @@ export declare class LifecycleManager {
     hasDeactivationHandlers<Value>(token: Token<Value> | Constructor<Value>): boolean;
     /** Every token carrying a container-level hook, paired with the phase that registered it. */
     hookedTokens(): Array<[DependencyKey, "onActivation" | "onDeactivation"]>;
-    runActivation<Value>(resolutionContext: ResolutionContext, binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): Promise<Value>;
+    /**
+     * Runs the activation pipeline on the async lane: the activated instance, or its promise once a
+     * hook has returned one.
+     *
+     * @remarks A level yields only where a hook does, so a synchronous pipeline hands the instance
+     * back in the caller's own tick and a singleton it activates is cached before any sibling reads it.
+     */
+    runActivation<Value>(resolutionContext: ResolutionContext, binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): Value | Promise<Value>;
     runActivationSync<Value>(resolutionContext: ResolutionContext, binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): Value;
     runDeactivation<Value>(binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): Promise<void>;
     runDeactivationSync<Value>(binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): void;