@codefast/di 0.10.1 → 0.12.0

package/dist/index.js

@@ -6,26 +6,27 @@ 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";
 // Decorators
 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, InvalidMetadataError, MissingContainerContextError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, 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/{resolve-options.js → dependency-slot.js}

@@ -49,15 +49,17 @@ function loneNameCriterionOf(options) {
 }
 /** Shared core: build a ResolveOptions from already-normalised name + tags. */
 function buildOptions(name, tags) {
-    if (name === undefined && tags === undefined) {
+    // An empty criterion list selects nothing, so it states no criterion at all.
+    const criteria = tags !== undefined && tags.length > 0 ? tags : undefined;
+    if (name === undefined && criteria === undefined) {
         return undefined;
     }
     const options = {};
     if (name !== undefined) {
         options.name = name;
     }
-    if (tags !== undefined) {
-        options.tags = tags;
+    if (criteria !== undefined) {
+        options.tags = criteria;
     }
     return options;
 }
@@ -85,7 +87,7 @@ const MEMOIZED_SINGLE_CRITERION = Symbol("di:single-criterion");
  */
 export function resolveOptionsForSlot(injectionSlot) {
     const { name, tags } = injectionSlot;
-    if (name === undefined && tags === undefined) {
+    if (name === undefined && (tags === undefined || tags.length === 0)) {
         return undefined;
     }
     const slot = injectionSlot;

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/injection/descriptor.js

@@ -4,12 +4,8 @@
  * @since 0.3.16-canary.0
  */
 export function isInjectionDescriptor(value) {
-    if (value === null || value === undefined) {
-        return false;
-    }
-    const type = typeof value;
-    // inject() returns a function (dual-role), so must check both object and function
-    if (type !== "object" && type !== "function") {
+    // inject() returns a function (dual-role), so both an object and a function qualify.
+    if ((typeof value !== "object" && typeof value !== "function") || value === null) {
         return false;
     }
     return ("token" in value &&
@@ -106,7 +102,7 @@ export function buildInjectionDescriptor(token, options) {
  */
 export function optional(token, options) {
     return withOptions({
-        token: token,
+        token,
         optional: true,
         multi: false,
     }, options);

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.
@@ -49,8 +49,13 @@ export interface GraphOptions {
     readonly includeParent?: boolean | undefined;
 }
 /**
- * Builds the JSON dependency graph of a registry's bindings, optionally including the parent's.
+ * Builds the JSON dependency graph of a registry's bindings, optionally including its ancestors'.
+ *
+ * @param registry - The registry whose bindings the graph is for.
+ * @param metadataReader - The reader class dependencies are read through.
+ * @param options - Whether the ancestors' bindings join the graph.
+ * @param ancestorRegistries - The ancestor containers' registries, nearest first.
  *
  * @since 0.3.16-canary.0
  */
-export declare function buildDependencyGraph(registry: BindingRegistry, metadataReader: MetadataReader, options: GraphOptions | undefined, parentRegistry?: BindingRegistry): ContainerGraphJson;
+export declare function buildDependencyGraph(registry: BindingRegistry, metadataReader: MetadataReader, options: GraphOptions | undefined, ancestorRegistries?: ReadonlyArray<BindingRegistry>): ContainerGraphJson;

package/dist/introspection/dependency-graph.js

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

package/dist/introspection/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/graph-adapters/reactflow.js

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

package/dist/introspection/inspector.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;