@codefast/di 0.8.1 → 0.10.0

package/dist/core/state-epoch.js

@@ -0,0 +1,21 @@
+/**
+ * The process-wide counter every container mutation advances, so a chain walk can be skipped while nothing moved.
+ */
+let epoch = 0;
+/**
+ * The current state epoch: unchanged between two reads exactly when no registry or lifecycle table
+ * in the process was mutated in between.
+ *
+ * @since 0.10.0
+ */
+export function stateEpoch() {
+    return epoch;
+}
+/**
+ * Advances the epoch; every registry version bump and every activation-hook registration calls it.
+ *
+ * @since 0.10.0
+ */
+export function advanceStateEpoch() {
+    epoch += 1;
+}

package/dist/core/tag.d.ts

@@ -59,12 +59,12 @@ export interface TagKey<Value = unknown> {
 /**
  * Declares a tag key, whose `of()` builds the criteria a `whenTagged` and a resolve both take.
  *
- * @remarks The value type is checked at both ends: a key declared `tag<Region>("region")` refuses a
+ * @remarks The value type is checked at both ends: a key declared `tag<Region>("di:region")` refuses a
  * value that is not a `Region`, so a bind site and a resolve site cannot drift apart silently.
  *
  * @example
  * ```ts
- * const Region = tag<"eu" | "us">("region");
+ * const Region = tag<"eu" | "us">("di:region");
  * container.bind(Storage).to(S3).whenTagged(Region.of("eu"));
  * container.resolve(Storage, { tag: Region.of("eu") });
  * ```

package/dist/core/tag.js

@@ -27,12 +27,12 @@ function internKeyFor(value) {
 /**
  * Declares a tag key, whose `of()` builds the criteria a `whenTagged` and a resolve both take.
  *
- * @remarks The value type is checked at both ends: a key declared `tag<Region>("region")` refuses a
+ * @remarks The value type is checked at both ends: a key declared `tag<Region>("di:region")` refuses a
  * value that is not a `Region`, so a bind site and a resolve site cannot drift apart silently.
  *
  * @example
  * ```ts
- * const Region = tag<"eu" | "us">("region");
+ * const Region = tag<"eu" | "us">("di:region");
  * container.bind(Storage).to(S3).whenTagged(Region.of("eu"));
  * container.resolve(Storage, { tag: Region.of("eu") });
  * ```

package/dist/core/token.d.ts

@@ -1,20 +1,40 @@
 import type { Constructor } from "#/core/constructor-type";
 declare const TOKEN_BRAND: unique symbol;
+declare const TOKEN_NAMES_BRAND: unique symbol;
 /**
- * A branded identifier carrying the value type its bindings resolve to.
+ * A branded identifier carrying the value type its bindings resolve to, and the slot names they may declare.
+ *
+ * @remarks `Names` exists at the type level only: `whenNamed`, and `name` in `ResolveOptions` and
+ * `InjectOptions`, narrow to it, so a bind site and a request site cannot drift apart silently. It
+ * is covariant, so a token declaring names is still a `Token<unknown>` wherever the engine erases
+ * the value type; the default `string` leaves a token that declares none unconstrained.
+ *
+ * @example
+ * ```ts
+ * const Logger = token<Logger, "console" | "file">("di:Logger");
+ * container.bind(Logger).to(FileLogger).whenNamed("file");
+ * container.resolve(Logger, { name: "file" });
+ * ```
  *
  * @since 0.3.16-canary.0
  */
-export interface Token<out Value> {
+export interface Token<out Value, out Names extends string = string> {
     readonly name: string;
     readonly [TOKEN_BRAND]: Value;
+    readonly [TOKEN_NAMES_BRAND]?: Names;
 }
 /**
- * Creates a named `Token` for the given value type.
+ * The slot names a dependency key declares — `string` for a class, or a token that declares none.
+ *
+ * @since 0.9.0
+ */
+export type SlotNamesOf<Key> = Key extends Token<unknown, infer Names extends string> ? Names : string;
+/**
+ * Creates a named `Token` for the given value type, optionally declaring the slot names its bindings may use.
  *
  * @since 0.3.16-canary.0
  */
-export declare function token<Value>(name: string): Token<Value>;
+export declare function token<Value, Names extends string = string>(name: string): Token<Value, Names>;
 /**
  * Returns the display name of a token or class used as a dependency key.
  *

package/dist/core/token.js

@@ -1,5 +1,5 @@
 /**
- * Creates a named `Token` for the given value type.
+ * Creates a named `Token` for the given value type, optionally declaring the slot names its bindings may use.
  *
  * @since 0.3.16-canary.0
  */

package/dist/core/types.d.ts

@@ -17,11 +17,14 @@ export type DependencyKey = Token<unknown> | Constructor;
 export type BindingScope = "singleton" | "transient" | "scoped";
 declare const BINDING_ID_BRAND: unique symbol;
 /**
- * A branded string that uniquely identifies one binding.
+ * A branded number that uniquely identifies one binding for the life of the process.
+ *
+ * @remarks Minted from a counter, never parsed or displayed as an identity: the brand is what makes
+ * it opaque, and a number costs a plain bind nothing where a string cost it an allocation.
  *
  * @since 0.3.16-canary.0
  */
-export type BindingIdentifier = string & {
+export type BindingIdentifier = number & {
     readonly [BINDING_ID_BRAND]: true;
 };
 /**
@@ -47,8 +50,14 @@ export type DeactivationHandler<Value> = (instance: Value) => void | Promise<voi
  *
  * @since 0.3.16-canary.0
  */
-export interface ResolveOptions {
-    name?: string | undefined;
+export interface ResolveOptions<Names extends string = string> {
+    /**
+     * The slot name a binding declared with `whenNamed`.
+     *
+     * @remarks Narrowed to the names the token declares, so a request cannot ask for a name no
+     * binding could carry; a token declaring none takes any string.
+     */
+    name?: Names | undefined;
     /**
      * Single-tag shorthand, equivalent to listing the one pair in `tags`.
      *
@@ -103,8 +112,8 @@ export interface ResolutionContext {
     resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
     resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
-    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
-    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): ReadonlyArray<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<ReadonlyArray<Value>>;
     readonly graph: ConstraintContext;
 }
 /**

package/dist/decorators/inject.d.ts

@@ -8,5 +8,5 @@ type ClassAccessorDecorator<This, Value> = (target: ClassAccessorDecoratorTarget
  *
  * @since 0.3.16-canary.0
  */
-export declare function inject<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
+export declare function inject<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<InjectOptions<Names>>): InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
 export {};

package/dist/decorators/inject.js

@@ -30,6 +30,8 @@ export function inject(token, options) {
     // Derived from the descriptor, not from `options`: the descriptor is where the tag shorthand has
     // already been folded. Built once here rather than per constructed instance.
     const resolveOptions = injectionSlotToResolveOptions(descriptor);
+    // The names are checked above; the container lane only needs the value type.
+    const resolveKey = token;
     const decoratorFn = (_target, context) => {
         if (context.static) {
             throw new StaticMemberDecoratorError("inject", String(context.name));
@@ -50,8 +52,8 @@ export function inject(token, options) {
             const ambient = getAmbientResolution();
             if (ambient !== undefined) {
                 const value = descriptor.optional
-                    ? ambient.resolveOptional(token, resolveOptions)
-                    : ambient.resolve(token, resolveOptions);
+                    ? ambient.resolveOptional(resolveKey, resolveOptions)
+                    : ambient.resolve(resolveKey, resolveOptions);
                 context.access.set(this, value);
                 return;
             }
@@ -60,8 +62,8 @@ export function inject(token, options) {
                 throw new MissingContainerContextError(classNameOf(this), context.name);
             }
             const value = descriptor.optional
-                ? container.resolveOptional(token, resolveOptions)
-                : container.resolve(token, resolveOptions);
+                ? container.resolveOptional(resolveKey, resolveOptions)
+                : container.resolve(resolveKey, resolveOptions);
             context.access.set(this, value);
         });
         return {};

package/dist/errors/diagnostics.d.ts

@@ -25,6 +25,8 @@ export interface ResolutionDiagnostics {
     readonly compiledPlanCount: number;
     /** Bindings with a compiled async instantiation plan. */
     readonly compiledAsyncPlanCount: number;
+    /** Plans this container's resolver has generated as functions of their own. */
+    readonly generatedPlanCount: number;
     /** Contexts held by the depth-indexed sync pool. */
     readonly syncContextPoolSize: number;
     /** Scoped instances currently cached by this container's scope manager. */

package/dist/errors/errors.d.ts

@@ -1,3 +1,4 @@
+import type { ConstraintRequirement } from "#/core/constraint-requirement";
 import type { BindingIdentifier, BindingScope, ResolveOptions } from "#/core/types";
 /**
  * Base class for every error the library throws, each carrying a machine-readable `code`.
@@ -132,8 +133,10 @@ export declare class UnreachableConstraintError extends DiError {
     readonly code = "UNREACHABLE_CONSTRAINT";
     readonly tokenName: string;
     readonly requiredName: string;
+    /** The token the name was required on, or `undefined` when the constraint named no token. */
+    readonly requiredTokenName: string | undefined;
     readonly helperName: string;
-    constructor(tokenName: string, requiredName: string, helperName: string);
+    constructor(tokenName: string, requirement: ConstraintRequirement);
 }
 /**
  * A container-level lifecycle hook whose token nothing is bound to, so it can never run.
@@ -229,6 +232,35 @@ export declare class MissingContainerContextError extends DiError {
  *
  * @since 0.5.0-canary.8
  */
+/**
+ * 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.
+ *
+ * @since 0.10.0
+ */
+export declare class ChainAlreadyRegisteredError extends DiError {
+    readonly code = "CHAIN_ALREADY_REGISTERED";
+    readonly tokenName: string;
+    constructor(tokenName: string);
+}
+/**
+ * `many()` on a binding with a named or tagged slot, or a slot constraint on a collection member.
+ *
+ * @remarks A collection member keeps the default slot: its membership replaces slot last-wins, and a
+ * tagged member would have no index able to return every member of the tag.
+ *
+ * @since 0.10.0
+ */
+export declare class ManyBindingSlotError extends DiError {
+    readonly code = "MANY_BINDING_SLOT";
+    readonly tokenName: string;
+    constructor(tokenName: string);
+}
+/**
+ * @since 0.10.0
+ */
 export declare class ChainNotRegisteredError extends DiError {
     readonly code = "CHAIN_NOT_REGISTERED";
     readonly tokenName: string;

package/dist/errors/errors.js

@@ -191,11 +191,17 @@ export class UnreachableConstraintError extends DiError {
     code = "UNREACHABLE_CONSTRAINT";
     tokenName;
     requiredName;
+    /** The token the name was required on, or `undefined` when the constraint named no token. */
+    requiredTokenName;
     helperName;
-    constructor(tokenName, requiredName, helperName) {
-        super(`The binding for '${tokenName}' is constrained by ${helperName}('${requiredName}'), but no binding in this container or its ancestors declares the slot name '${requiredName}', so the constraint can never hold. Name the slot with .whenNamed('${requiredName}') on the binding it should match, or correct the name here.`);
+    constructor(tokenName, requirement) {
+        const { name, helperName, tokenName: requiredTokenName } = requirement;
+        const scope = requiredTokenName === undefined ? "no binding" : `no binding for '${requiredTokenName}'`;
+        const target = requiredTokenName === undefined ? "the binding it should match" : `a '${requiredTokenName}' binding`;
+        super(`The binding for '${tokenName}' is constrained by ${helperName} waiting on the slot name '${name}', but ${scope} in this container or its ancestors declares it, so the constraint can never hold. Name the slot with .whenNamed('${name}') on ${target}, or correct the name here.`);
         this.tokenName = tokenName;
-        this.requiredName = requiredName;
+        this.requiredName = name;
+        this.requiredTokenName = requiredTokenName;
         this.helperName = helperName;
     }
 }
@@ -319,6 +325,41 @@ export class MissingContainerContextError extends DiError {
  *
  * @since 0.5.0-canary.8
  */
+/**
+ * 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.
+ *
+ * @since 0.10.0
+ */
+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.`);
+        this.tokenName = tokenName;
+    }
+}
+/**
+ * `many()` on a binding with a named or tagged slot, or a slot constraint on a collection member.
+ *
+ * @remarks A collection member keeps the default slot: its membership replaces slot last-wins, and a
+ * tagged member would have no index able to return every member of the tag.
+ *
+ * @since 0.10.0
+ */
+export class ManyBindingSlotError extends DiError {
+    code = "MANY_BINDING_SLOT";
+    tokenName;
+    constructor(tokenName) {
+        super(`A many() binding for token '${tokenName}' keeps the default slot: it cannot also declare whenNamed() or whenTagged().`);
+        this.tokenName = tokenName;
+    }
+}
+/**
+ * @since 0.10.0
+ */
 export class ChainNotRegisteredError extends DiError {
     code = "CHAIN_NOT_REGISTERED";
     tokenName;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { ActivationHandler, BindingConstraint, BindingIdentifier, BindingKind, BindingScope, BindingTag, ConstraintContext, Constructor, DependencyKey, DeactivationHandler, ResolutionFrame, ResolveOptions, ResolutionContext, TokenValue, } from "#/core/types";
 export { token, tokenName } from "#/core/token";
-export type { Token } 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";
@@ -25,7 +25,7 @@ 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 { whenAnyAncestorIs, whenAnyAncestorNamed, whenAnyAncestorTagged, whenAnyAncestorTaggedAll, whenNoAncestorIs, whenNoParentIs, whenParentIs, whenParentNamed, whenParentTagged, whenParentTaggedAll, } from "#/resolution/select/constraints";
-export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainNotRegisteredError, 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, InvalidMetadataError, MissingContainerContextError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#/errors/errors";
 export type { ScopeViolationDetails } from "#/errors/errors";
 export { toDotGraph } from "#/introspection/graph-adapters/dot";
 export { toCytoscapeGraph } from "#/introspection/graph-adapters/cytoscape";

package/dist/index.js

@@ -25,7 +25,7 @@ export { defaultMetadataReader, SymbolMetadataReader } from "#/metadata/symbol-m
 // 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, ChainNotRegisteredError, 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, InvalidMetadataError, MissingContainerContextError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#/errors/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

@@ -7,8 +7,14 @@ import type { DependencySlot } from "#/injection/resolve-options";
  *
  * @since 0.3.16-canary.0
  */
-export interface InjectOptions {
-    name?: string | undefined;
+export interface InjectOptions<Names extends string = string> {
+    /**
+     * The slot name a binding declared with `whenNamed`.
+     *
+     * @remarks Narrowed to the names the token declares, so a dependency cannot ask for a name no
+     * binding could carry; a token declaring none takes any string.
+     */
+    name?: Names | undefined;
     /**
      * Single-tag shorthand, equivalent to listing the one pair in `tags`.
      *
@@ -45,7 +51,7 @@ export type InjectableDependency<Value = unknown> = Token<Value> | Constructor<V
  */
 export type ResolvedDependencyValue<Dependency> = Dependency extends {
     readonly multi: true;
-} ? Array<DescribedValue<Dependency>> : Dependency extends {
+} ? ReadonlyArray<DescribedValue<Dependency>> : Dependency extends {
     readonly optional: true;
 } ? DescribedValue<Dependency> | undefined : DescribedValue<Dependency>;
 /**
@@ -53,7 +59,7 @@ export type ResolvedDependencyValue<Dependency> = Dependency extends {
  *
  * @remarks Split out because a hand-written descriptor states its flags and its value type
  * separately, and only the flags are load-bearing: `{ token: Plugin, multi: true }` says `Plugin`
- * and delivers `Array<Plugin>`. `injectAll()` and `optional()` already fold their effect in, so the
+ * and delivers `ReadonlyArray<Plugin>`. `injectAll()` and `optional()` already fold their effect in, so the
  * flags find an array or an optional there and leave it alone.
  */
 type DescribedValue<Dependency> = Dependency extends InjectionDescriptor<infer Value> ? Value : TokenValue<Dependency>;
@@ -74,17 +80,19 @@ export declare function normalizeToDescriptor(dependency: InjectableDependency):
  *
  * @since 0.6.0
  */
-export declare function buildInjectionDescriptor<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Value>;
+export declare function buildInjectionDescriptor<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<InjectOptions<Names>>): InjectionDescriptor<Value>;
 /**
  * Creates a descriptor that resolves to `undefined` instead of throwing when no binding matches.
  *
  * @since 0.3.16-canary.0
  */
-export declare function optional<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Value | undefined>;
+export declare function optional<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<InjectOptions<Names>>): InjectionDescriptor<Value | undefined>;
 /**
- * Creates a descriptor that resolves every matching binding for the token into an array.
+ * Creates a descriptor that resolves every matching binding for the token into a read-only array.
+ *
+ * @remarks Read-only because a root-level read may hand out the engine's own cached list.
  *
  * @since 0.3.16-canary.0
  */
-export declare function injectAll<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Array<Value>>;
+export declare function injectAll<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<InjectOptions<Names>>): InjectionDescriptor<ReadonlyArray<Value>>;
 export {};

package/dist/injection/descriptor.js

@@ -112,7 +112,9 @@ export function optional(token, options) {
     }, options);
 }
 /**
- * Creates a descriptor that resolves every matching binding for the token into an array.
+ * Creates a descriptor that resolves every matching binding for the token into a read-only array.
+ *
+ * @remarks Read-only because a root-level read may hand out the engine's own cached list.
  *
  * @since 0.3.16-canary.0
  */

package/dist/injection/resolve-options.d.ts

@@ -26,6 +26,12 @@ export interface DependencySlot {
  * @since 0.5.0-canary.9
  */
 export declare function singleCriterionOnlyOf(options: ResolveOptions | undefined): BindingTag | undefined;
+/**
+ * The one tag a request carries beside its name, for the name-plus-tag lane; `undefined` for every other shape.
+ *
+ * @since 0.10.0
+ */
+export declare function loneTagBesideNameOf(options: ResolveOptions): BindingTag | undefined;
 /**
  * Builds a {@link ResolveOptions} safe for `exactOptionalPropertyTypes`:
  * omits keys instead of assigning `undefined`.

package/dist/injection/resolve-options.js

@@ -22,6 +22,22 @@ export function singleCriterionOnlyOf(options) {
     }
     return listed !== undefined && listed.length === 1 ? listed[0] : undefined;
 }
+/**
+ * The one tag a request carries beside its name, for the name-plus-tag lane; `undefined` for every other shape.
+ *
+ * @since 0.10.0
+ */
+export function loneTagBesideNameOf(options) {
+    if (options.name === undefined) {
+        return undefined;
+    }
+    const listed = options.tags;
+    const shorthand = options.tag;
+    if (shorthand !== undefined) {
+        return listed === undefined || listed.length === 0 ? shorthand : undefined;
+    }
+    return listed !== undefined && listed.length === 1 ? listed[0] : undefined;
+}
 /** The name spelling's half of the fold, kept apart so the common body stays small enough to inline. */
 function loneNameCriterionOf(options) {
     // A name next to any tag means the request carries two criteria, which no single index answers.

package/dist/introspection/dependency-graph.js

@@ -100,7 +100,7 @@ function addDependencyEdges(accumulator, from, ref, index, lookup) {
             : label;
         accumulator.edges.push({
             from,
-            to: target.id,
+            to: String(target.identifier),
             label: perTargetLabel,
             optional: ref.optional,
             ...(edgeSlotName !== undefined ? { slotName: edgeSlotName } : {}),
@@ -113,21 +113,26 @@ function addBindingEdges(accumulator, binding, metadataReader, lookup) {
         const meta = metadataReader.getConstructorMetadata(binding.target);
         if (meta !== undefined) {
             for (const [index, param] of meta.params.entries()) {
-                addDependencyEdges(accumulator, binding.id, param, index, lookup);
+                addDependencyEdges(accumulator, String(binding.identifier), param, index, lookup);
             }
         }
         return;
     }
     if (binding.kind === "resolved" || binding.kind === "resolved-async") {
         for (const [index, dependency] of binding.deps.entries()) {
-            addDependencyEdges(accumulator, binding.id, dependency, index, lookup);
+            addDependencyEdges(accumulator, String(binding.identifier), dependency, index, lookup);
         }
         return;
     }
     if (binding.kind === "alias") {
         const aliasRef = { token: binding.target, optional: false, multi: false };
         for (const target of matchingTargets(lookup(binding.target), aliasRef)) {
-            accumulator.edges.push({ from: binding.id, to: target.id, label: "alias", optional: false });
+            accumulator.edges.push({
+                from: String(binding.identifier),
+                to: String(target.identifier),
+                label: "alias",
+                optional: false,
+            });
         }
     }
 }
@@ -135,7 +140,7 @@ function addRegistryBindings(accumulator, sourceRegistry, metadataReader, fromPa
     const lookup = bindingLookup(sourceRegistry, fallbackRegistry);
     for (const binding of sourceRegistry.allBindings()) {
         accumulator.nodes.push({
-            id: binding.id,
+            id: String(binding.identifier),
             tokenName: tokenName(binding.token),
             tokenKey: tokenKeyOf(binding.token),
             kind: binding.kind,

package/dist/introspection/inspector.d.ts

@@ -16,6 +16,8 @@ export interface BindingSnapshot {
         readonly tags: ReadonlyArray<BindingTag>;
     };
     readonly id: BindingIdentifier;
+    /** Whether the binding is a collection member only, taken by `resolveAll` and never by `resolve`. */
+    readonly isMany: boolean;
 }
 /**
  * A read-only view of one container's own bindings and state.
@@ -38,6 +40,6 @@ export declare class Inspector {
     constructor(registry: BindingRegistry, scope: ScopeManager, hasParent: boolean, isDisposed: () => boolean);
     inspect(): ContainerSnapshot;
     lookupBindings<Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot>;
-    has(token: Token<unknown> | Constructor, options?: ResolveOptions, parentHas?: () => boolean): boolean;
+    /** Whether this container's own registry holds a binding the request could select. */
     hasOwn(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean;
 }

package/dist/introspection/inspector.js

@@ -30,31 +30,16 @@ export class Inspector {
         const bindings = this.#registry.getAll(token);
         return bindings.map((binding) => this.#toSnapshot(binding));
     }
-    has(token, options, parentHas) {
-        const bindings = this.#registry.getAll(token);
-        if (bindings.length > 0) {
-            // An existence probe answers ambiguity with `true` — several matches still exist; only
-            // resolution has to pick one.
-            if (options !== undefined) {
-                if (selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0) {
-                    return true;
-                }
-            }
-            else {
-                return true;
-            }
-        }
-        return parentHas?.() ?? false;
-    }
+    /** Whether this container's own registry holds a binding the request could select. */
     hasOwn(token, options) {
-        const bindings = this.#registry.getAll(token);
-        if (bindings.length === 0) {
-            return false;
-        }
-        if (options !== undefined) {
-            return selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0;
+        // Presence alone is a registry probe; only a request carrying criteria has to see the list.
+        if (options === undefined) {
+            return this.#registry.has(token);
         }
-        return true;
+        const bindings = this.#registry.getAll(token);
+        // An existence probe answers ambiguity with `true` — several matches still exist; only
+        // resolution has to pick one.
+        return bindings.length > 0 && selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0;
     }
     #makeConstraintContext(options) {
         return {
@@ -76,7 +61,8 @@ export class Inspector {
             kind: binding.kind,
             scope: effectiveBindingScope(binding),
             slot,
-            id: binding.id,
+            id: binding.identifier,
+            isMany: binding.isMany,
         };
     }
 }

package/dist/lifecycle/lifecycle-manager.js

@@ -1,4 +1,5 @@
 import { getOrInsert } from "#/core/map-upsert";
+import { advanceStateEpoch } from "#/core/state-epoch";
 import { tokenName } from "#/core/token";
 import { AsyncActivationError, AsyncDeactivationError, InvalidMetadataError } from "#/errors/errors";
 /**
@@ -18,6 +19,7 @@ export class LifecycleManager {
     #cachedHooks;
     registerActivation(token, handler) {
         this.#activationVersion += 1;
+        advanceStateEpoch();
         this.#cachedToken = undefined;
         this.#cachedHooks = undefined;
         this.#activationHooks ??= new Map();
@@ -77,8 +79,8 @@ export class LifecycleManager {
             }
         }
         // 2. per-binding onActivation
-        if (binding.kind !== "alias" && binding.onActivation !== undefined) {
-            const activationResult = binding.onActivation(resolutionContext, activatedInstance);
+        if (binding.kind !== "alias" && binding.activationHook !== undefined) {
+            const activationResult = binding.activationHook(resolutionContext, activatedInstance);
             activatedInstance = activationResult instanceof Promise ? await activationResult : activationResult;
         }
         // 3. container-level onActivation
@@ -100,8 +102,8 @@ export class LifecycleManager {
             }
         }
         // 2. per-binding onActivation (must be sync)
-        if (binding.kind !== "alias" && binding.onActivation !== undefined) {
-            const activationResult = binding.onActivation(resolutionContext, activatedInstance);
+        if (binding.kind !== "alias" && binding.activationHook !== undefined) {
+            const activationResult = binding.activationHook(resolutionContext, activatedInstance);
             if (activationResult instanceof Promise) {
                 throw new AsyncActivationError(tokenName(binding.token), "onActivation");
             }
@@ -134,8 +136,8 @@ export class LifecycleManager {
             }
         }
         // 2. per-binding onDeactivation
-        if (binding.kind !== "alias" && binding.onDeactivation !== undefined) {
-            const hookResult = binding.onDeactivation(instance);
+        if (binding.kind !== "alias" && binding.deactivationHook !== undefined) {
+            const hookResult = binding.deactivationHook(instance);
             if (hookResult instanceof Promise) {
                 await hookResult;
             }
@@ -162,8 +164,8 @@ export class LifecycleManager {
             }
         }
         // 2. per-binding onDeactivation
-        if (binding.kind !== "alias" && binding.onDeactivation !== undefined) {
-            const hookResult = binding.onDeactivation(instance);
+        if (binding.kind !== "alias" && binding.deactivationHook !== undefined) {
+            const hookResult = binding.deactivationHook(instance);
             if (hookResult instanceof Promise) {
                 throw new AsyncDeactivationError(tokenDisplayName);
             }

package/dist/lifecycle/scope-manager.js

@@ -99,7 +99,7 @@ export class ScopeManager {
         if (!this.isChild) {
             throw new MissingScopeContextError(tokenName(binding.token));
         }
-        (this.#scoped ??= new Map()).set(binding.id, instance);
+        (this.#scoped ??= new Map()).set(binding.identifier, instance);
     }
     /** Releases a removed binding's scoped instance. A scoped instance has no deactivation. */
     deleteScoped(id) {