@codefast/di 0.5.0 → 0.6.1

package/src/{errors.ts → errors/errors.ts}

@@ -1,4 +1,4 @@
-import type { BindingIdentifier, BindingScope, ResolveOptions } from "#/types";
+import type { BindingIdentifier, BindingScope, ResolveOptions } from "#/core/types";
 
 /**
  * @since 0.3.16-canary.0
@@ -36,6 +36,19 @@ export class TokenNotBoundError extends DiError {
   }
 }
 
+// Options carry caller values a tag may hold — a bigint or a circular object must not make the
+// diagnostic itself throw and mask the real error.
+function describeResolveOptions(options: ResolveOptions): string {
+  try {
+    return (
+      JSON.stringify(options, (_key, value: unknown) => (typeof value === "bigint" ? `${String(value)}n` : value)) ??
+      "undefined"
+    );
+  } catch {
+    return "[unserializable options]";
+  }
+}
+
 /**
  * @since 0.3.16-canary.0
  */
@@ -46,7 +59,7 @@ export class NoMatchingBindingError extends DiError {
   readonly availableSlots: Array<string>;
 
   constructor(tokenName: string, options: ResolveOptions, availableSlots: Array<string>) {
-    const optionsString = JSON.stringify(options);
+    const optionsString = describeResolveOptions(options);
     const slotsStr = availableSlots.join(", ");
     super(`No binding for '${tokenName}' matching ${optionsString}. Available slots: [${slotsStr}].`);
     this.tokenName = tokenName;
@@ -90,12 +103,16 @@ export class CircularDependencyError extends DiError {
  */
 export class AsyncResolutionError extends DiError {
   readonly code = "ASYNC_RESOLUTION";
+  /** The token the caller asked for — what `resolveAsync` has to be called with. */
   readonly tokenName: string;
+  /** The token whose factory is async: `tokenName` itself unless a dependency forced it. */
   readonly asyncSourceToken: string;
 
-  constructor(tokenName: string, asyncSourceToken: string) {
+  constructor(tokenName: string, asyncSourceToken: string = tokenName) {
     super(
-      `Token '${tokenName}' requires async resolution because '${asyncSourceToken}' in its dependency chain has an async factory. Use container.resolveAsync(${tokenName}).`,
+      asyncSourceToken === tokenName
+        ? `Token '${tokenName}' requires async resolution because its factory is async. Use container.resolveAsync(${tokenName}).`
+        : `Token '${tokenName}' requires async resolution because '${asyncSourceToken}' in its dependency chain has an async factory. Use container.resolveAsync(${tokenName}).`,
     );
     this.tokenName = tokenName;
     this.asyncSourceToken = asyncSourceToken;
@@ -141,6 +158,98 @@ export class ScopeViolationError extends DiError {
   }
 }
 
+/**
+ * A `…TaggedAll` constraint built from a criteria list with nothing in it.
+ *
+ * @remarks Reported where the list is passed rather than where it fails to match, because it does
+ * not fail to match — "carries all of no criteria" holds for any ancestor, so the constraint quietly
+ * becomes a weaker one that still outranks an unconstrained binding.
+ *
+ * @since 0.6.0
+ */
+export class EmptyTagCriteriaError extends DiError {
+  readonly code = "EMPTY_TAG_CRITERIA";
+  readonly helperName: string;
+
+  constructor(helperName: string) {
+    super(
+      `${helperName}() was given no criteria. An empty list matches any ancestor, which is not what the call says — pass the criteria to require, or drop the constraint if there are none.`,
+    );
+    this.helperName = helperName;
+  }
+}
+
+/**
+ * A constraint waiting on a slot name that nothing in the container chain declares.
+ *
+ * @remarks A name is a bare string, so a typo produces a constraint that is never satisfied and
+ * never reported. Reported by `validate()` rather than at bind time, because the binding carrying
+ * the name may be registered after the constraint is built.
+ *
+ * @since 0.6.0
+ */
+export class UnreachableConstraintError extends DiError {
+  readonly code = "UNREACHABLE_CONSTRAINT";
+  readonly tokenName: string;
+  readonly requiredName: string;
+  readonly helperName: string;
+
+  constructor(tokenName: string, requiredName: string, helperName: string) {
+    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.`,
+    );
+    this.tokenName = tokenName;
+    this.requiredName = requiredName;
+    this.helperName = helperName;
+  }
+}
+
+/**
+ * A container-level lifecycle hook whose token nothing is bound to, so it can never run.
+ *
+ * @remarks Hooks are keyed by token identity, which makes a class that is only ever a `to()` target
+ * look like a token and match nothing. Reported by `validate()` rather than at registration, because
+ * binding after registering the hook is a supported order.
+ *
+ * @since 0.6.0
+ */
+export class UnreachableLifecycleHookError extends DiError {
+  readonly code = "UNREACHABLE_LIFECYCLE_HOOK";
+  readonly tokenName: string;
+  readonly phase: "onActivation" | "onDeactivation";
+
+  constructor(tokenName: string, phase: "onActivation" | "onDeactivation") {
+    super(
+      `${phase}() is registered for '${tokenName}', which nothing is bound to in this container or its ancestors, so the hook can never run. Bind the token, or — if '${tokenName}' is a class you bound as an implementation via .to(${tokenName}) — register the hook against the token you bound instead.`,
+    );
+    this.tokenName = tokenName;
+    this.phase = phase;
+  }
+}
+
+/**
+ * A {@link MetadataReader} described a class with something the container cannot use.
+ *
+ * @remarks Separate from {@link MissingMetadataError}: absent metadata is a class the container was
+ * never told about, while invalid metadata is a reader that answered wrongly. Covers both the
+ * constructor answer and the lifecycle one, since only the `reason` differs.
+ *
+ * @since 0.6.0
+ */
+export class InvalidMetadataError extends DiError {
+  readonly code = "INVALID_METADATA";
+  readonly targetName: string;
+  readonly reason: string;
+
+  constructor(targetName: string, reason: string) {
+    super(
+      `MetadataReader returned invalid metadata for class '${targetName}': ${reason}. Check the reader bound to MetadataReaderToken or passed to Container.create().`,
+    );
+    this.targetName = targetName;
+    this.reason = reason;
+  }
+}
+
 /**
  * @since 0.3.16-canary.0
  */
@@ -198,17 +307,29 @@ export class MissingScopeContextError extends DiError {
 }
 
 /**
+ * An `@inject` accessor initialized with no container context open.
+ *
+ * @remarks Carries the class and the accessor separately: a nameless class is possible (an anonymous
+ * class expression has an empty `name`), and a message that claims a class it does not have is what
+ * sent readers looking for a class called `clock`.
+ *
  * @since 0.3.16-canary.0
  */
 export class MissingContainerContextError extends DiError {
   readonly code = "MISSING_CONTAINER_CONTEXT";
-  readonly targetName: string;
+  /** The class being constructed, or `undefined` when it has no readable name. */
+  readonly className: string | undefined;
+  readonly accessorName: string | symbol;
 
-  constructor(targetName: string) {
+  constructor(className: string | undefined, accessorName: string | symbol) {
+    const accessor = `@inject accessor '${String(accessorName)}'`;
     super(
-      `Class '${targetName}' has @inject accessor fields but was instantiated outside a container context. Resolve it via container.resolve(${targetName}) instead.`,
+      className === undefined
+        ? `An ${accessor} was initialized outside a container context. Resolve its class through a container, or open a context with runWithContainer().`
+        : `Class '${className}' has an ${accessor} but was constructed outside a container context. Resolve it via container.resolve(${className}), or open a context with runWithContainer().`,
     );
-    this.targetName = targetName;
+    this.className = className;
+    this.accessorName = accessorName;
   }
 }
 
@@ -265,6 +386,29 @@ export class SelfBindingRequiresClassError extends DiError {
   }
 }
 
+/**
+ * A decorator that acts on one instance was applied to a static member.
+ *
+ * @remarks Instance-only by construction: `@inject` resolves through the container active while an
+ * instance is built, and `@postConstruct`/`@preDestroy` bracket one instance's lifecycle. A static
+ * member belongs to the class, which no container constructs.
+ *
+ * @since 0.6.0
+ */
+export class StaticMemberDecoratorError extends DiError {
+  readonly code = "STATIC_MEMBER_DECORATOR";
+  readonly decoratorName: string;
+  readonly memberName: string;
+
+  constructor(decoratorName: string, memberName: string) {
+    super(
+      `@${decoratorName}() applies to instance members only, and '${memberName}' is static. Move it to an instance member, or read the value from the container where the static member is used.`,
+    );
+    this.decoratorName = decoratorName;
+    this.memberName = memberName;
+  }
+}
+
 /**
  * @since 0.3.16-canary.0
  */

package/src/index.ts

@@ -1,6 +1,7 @@
 // Foundation types
 export type {
   ActivationHandler,
+  BindingConstraint,
   BindingIdentifier,
   BindingKind,
   BindingScope,
@@ -13,11 +14,15 @@ export type {
   ResolveOptions,
   ResolutionContext,
   TokenValue,
-} from "#/types";
+} from "#/core/types";
 
 // Token
-export { token, tokenName, isToken } from "#/token";
-export type { Token } from "#/token";
+export { token, tokenName } from "#/core/token";
+export type { Token } from "#/core/token";
+
+// Tag — the interned slot criteria a `whenTagged` and a resolve both take
+export { coversTagKeys, NO_TAG_KEYS, tag, tagKeyMaskOf } from "#/core/tag";
+export type { TagKey, TagKeyMask } from "#/core/tag";
 
 // Binding builders — types only
 export type {
@@ -30,15 +35,24 @@ export type {
   SingletonLifecycleBuilder,
   SlotConstrainedBuilder,
   TransientBindingBuilder,
-} from "#/binding";
+} from "#/core/binding";
 
 // Container
 export { Container } from "#/container/container";
-export type { Container as ContainerInterface, ContainerStatic } from "#/container/container";
+export type { Container as ContainerInterface, ContainerOptions, ContainerStatic } 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";
 
 // `effectiveBindingScope` is deliberately absent: it reads a `Binding`, which is internal, and no
 // public API hands one out. `BindingSnapshot.scope` and `GraphNode.scope` are the public answers.
-export { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolution/resolve-options";
+export {
+  bindingSlotToResolveOptions,
+  injectionSlotToResolveOptions,
+  resolveOptionsForSlot,
+} from "#/injection/resolve-options";
+export type { DependencySlot } from "#/injection/resolve-options";
 
 // Introspection types
 export type { BindingSnapshot, ContainerSnapshot } from "#/introspection/inspector";
@@ -47,12 +61,13 @@ export type { BindingSnapshot, ContainerSnapshot } from "#/introspection/inspect
 export type { ContainerGraphJson, GraphEdge, GraphNode, GraphOptions } from "#/introspection/dependency-graph";
 
 // Module
-export { AsyncModule, isSyncModule, Module, SyncModule } from "#/module";
-export type { AsyncModuleBuilder, ModuleBuilder } from "#/module";
+export { AsyncModule, isSyncModule, Module, SyncModule } from "#/core/module";
+export type { AsyncModuleBuilder, ModuleBuilder } from "#/core/module";
 
 // Decorators
-export { inject, injectAll, isInjectionDescriptor, optional } from "#/decorators/inject";
-export type { InjectionDescriptor, InjectOptions } from "#/decorators/inject";
+export { inject } from "#/decorators/inject";
+export { injectAll, isInjectionDescriptor, optional } from "#/injection/descriptor";
+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";
@@ -61,9 +76,16 @@ export { postConstruct, preDestroy } from "#/decorators/lifecycle-decorators";
 export { createAutoRegisterRegistry } from "#/decorators/injectable";
 export type { AutoRegisterRegistry } from "#/decorators/injectable";
 
-// MetadataReader
+// MetadataReader — everything a consumer needs to write one and pass it to Container.create()
 export { MetadataReaderToken } from "#/metadata/metadata-reader-token";
-export type { MetadataReader, MutableLifecycleMetadata } from "#/metadata/metadata-types";
+export type {
+  ConstructorMetadata,
+  LifecycleMetadata,
+  MetadataReader,
+  MutableLifecycleMetadata,
+  ParamMetadata,
+} from "#/metadata/metadata-types";
+export { defaultMetadataReader, SymbolMetadataReader } from "#/metadata/symbol-metadata-reader";
 
 // Constraints — contextual injection predicates for .when()
 export {
@@ -77,7 +99,7 @@ export {
   whenParentNamed,
   whenParentTagged,
   whenParentTaggedAll,
-} from "#/resolution/constraints";
+} from "#/resolution/select/constraints";
 
 // Errors
 export {
@@ -91,6 +113,7 @@ export {
   DiError,
   DisposedContainerError,
   InternalError,
+  InvalidMetadataError,
   MissingContainerContextError,
   MissingMetadataError,
   MissingScopeContextError,
@@ -98,10 +121,14 @@ export {
   RebindUnboundTokenError,
   ScopeViolationError,
   SelfBindingRequiresClassError,
+  StaticMemberDecoratorError,
   SyncDisposalNotSupportedError,
+  EmptyTagCriteriaError,
   TokenNotBoundError,
-} from "#/errors";
-export type { ScopeViolationDetails } from "#/errors";
+  UnreachableConstraintError,
+  UnreachableLifecycleHookError,
+} from "#/errors/errors";
+export type { ScopeViolationDetails } from "#/errors/errors";
 
 // Graph adapters — render `generateDependencyGraph()` output for common viewers
 export { toDotGraph } from "#/introspection/graph-adapters/dot";
@@ -109,3 +136,4 @@ export { toCytoscapeGraph } from "#/introspection/graph-adapters/cytoscape";
 export type { CytoscapeEdge, CytoscapeElements, CytoscapeNode } from "#/introspection/graph-adapters/cytoscape";
 export { toReactFlowGraph } from "#/introspection/graph-adapters/reactflow";
 export type { ReactFlowEdge, ReactFlowGraph, ReactFlowNode } from "#/introspection/graph-adapters/reactflow";
+export { toMermaidGraph } from "#/introspection/graph-adapters/mermaid";

package/src/injection/descriptor.ts

@@ -0,0 +1,206 @@
+/** 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";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface InjectOptions {
+  name?: string | undefined;
+  /**
+   * Single-tag shorthand, equivalent to listing the one pair in `tags`.
+   *
+   * @remarks Folded into `tags` when the descriptor is built, so nothing downstream sees two
+   * spellings of one request. Giving both is a request for every pair across the two.
+   */
+  tag?: BindingTag | undefined;
+  tags?: ReadonlyArray<BindingTag> | undefined;
+}
+
+/**
+ * One dependency a `toResolved` factory or an `@inject` accessor declares.
+ *
+ * @remarks Extends {@link DependencySlot} so the two dependency sources stay literally one shape,
+ * narrowing only `token` to carry the value type a factory's parameter is checked against.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface InjectionDescriptor<out Value = unknown> extends DependencySlot {
+  readonly token: Token<Value> | Constructor<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export type InjectableDependency<Value = unknown> = Token<Value> | Constructor<Value> | InjectionDescriptor<Value>;
+
+/**
+ * The value a factory receives for one declared dependency.
+ *
+ * @remarks `optional()` and `injectAll()` fold their effect into the descriptor's own type
+ * parameter, so reading it back is enough; bare tokens fall through to {@link TokenValue}.
+ *
+ * @since 0.5.0-canary.7
+ */
+export type ResolvedDependencyValue<Dependency> = Dependency extends { readonly multi: true }
+  ? Array<DescribedValue<Dependency>>
+  : Dependency extends { readonly optional: true }
+    ? DescribedValue<Dependency> | undefined
+    : DescribedValue<Dependency>;
+
+/**
+ * The value a dependency's own type parameter carries, before its flags are read.
+ *
+ * @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
+ * flags find an array or an optional there and leave it alone.
+ */
+type DescribedValue<Dependency> = Dependency extends InjectionDescriptor<infer Value> ? Value : TokenValue<Dependency>;
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function isInjectionDescriptor(value: unknown): value is InjectionDescriptor {
+  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") {
+    return false;
+  }
+  return (
+    "token" in (value as object) &&
+    "optional" in (value as object) &&
+    "multi" in (value as object) &&
+    typeof (value as InjectionDescriptor).optional === "boolean" &&
+    typeof (value as InjectionDescriptor).multi === "boolean"
+  );
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function normalizeToDescriptor(dependency: InjectableDependency): InjectionDescriptor {
+  if (isInjectionDescriptor(dependency)) {
+    return materializeInjectionDescriptor(dependency);
+  }
+  return { token: dependency, optional: false, multi: false };
+}
+
+/**
+ * Dual-role `inject()` values are functions: [[Function]].name must not be treated as a DI slot name.
+ * Only enumerable own `name` / `tags` from `Object.defineProperties` are real injection options.
+ */
+function materializeInjectionDescriptor(dependency: InjectionDescriptor): InjectionDescriptor {
+  if (typeof dependency !== "function") {
+    return dependency;
+  }
+  const dualRole = dependency as InjectionDescriptor & ((...args: Array<unknown>) => unknown);
+  const base: Pick<InjectionDescriptor, "token" | "optional" | "multi"> = {
+    token: dualRole.token,
+    optional: dualRole.optional,
+    multi: dualRole.multi,
+  };
+  const nameDesc = Object.getOwnPropertyDescriptor(dualRole, "name");
+  const tagsDesc = Object.getOwnPropertyDescriptor(dualRole, "tags");
+  const explicitName = nameDesc?.enumerable === true && typeof nameDesc.value === "string" ? nameDesc.value : undefined;
+  // Annotated because `PropertyDescriptor.value` is `any`, and an `any` reaching the cast below
+  // would make it look checked when nothing checked it.
+  const explicitTags: unknown = tagsDesc?.enumerable === true ? tagsDesc.value : undefined;
+
+  if (explicitName !== undefined && explicitTags !== undefined) {
+    return {
+      ...base,
+      name: explicitName,
+      tags: explicitTags as NonNullable<InjectionDescriptor["tags"]>,
+    };
+  }
+  if (explicitName !== undefined) {
+    return { ...base, name: explicitName };
+  }
+  if (explicitTags !== undefined) {
+    return { ...base, tags: explicitTags as NonNullable<InjectionDescriptor["tags"]> };
+  }
+  return base;
+}
+
+/**
+ * The one tag list a request carries, with the single-tag shorthand folded in.
+ *
+ * @remarks Folding here is what keeps `tag` from reaching `InjectionDescriptor` and everything
+ * derived from it, so one request never has two spellings past this point.
+ */
+function requestedTagsOf(options: InjectOptions | undefined): ReadonlyArray<BindingTag> | undefined {
+  const shorthand = options?.tag;
+  const listed = options?.tags;
+  if (shorthand === undefined) {
+    return listed;
+  }
+  return listed === undefined || listed.length === 0 ? [shorthand] : [shorthand, ...listed];
+}
+
+function withOptions<DescValue>(
+  base: Pick<InjectionDescriptor<DescValue>, "token" | "optional" | "multi">,
+  options: InjectOptions | undefined,
+): InjectionDescriptor<DescValue> {
+  const tags = requestedTagsOf(options);
+  if (options?.name !== undefined && tags !== undefined) {
+    return { ...base, name: options.name, tags };
+  }
+  if (options?.name !== undefined) {
+    return { ...base, name: options.name };
+  }
+  if (tags !== undefined) {
+    return { ...base, tags };
+  }
+  return base;
+}
+
+/**
+ * The descriptor half of `inject()`, shared with the accessor decorator that wraps it.
+ *
+ * @since 0.6.0
+ */
+export function buildInjectionDescriptor<Value>(
+  token: Token<Value> | Constructor<Value>,
+  options?: InjectOptions,
+): InjectionDescriptor<Value> {
+  return withOptions({ token, optional: false, multi: false }, options);
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function optional<Value>(
+  token: Token<Value> | Constructor<Value>,
+  options?: InjectOptions,
+): InjectionDescriptor<Value | undefined> {
+  return withOptions(
+    {
+      token: token as Token<Value | undefined> | Constructor<Value | undefined>,
+      optional: true,
+      multi: false,
+    },
+    options,
+  );
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function injectAll<Value>(
+  token: Token<Value> | Constructor<Value>,
+  options?: InjectOptions,
+): InjectionDescriptor<Array<Value>> {
+  return withOptions(
+    {
+      token: token as Token<Array<Value>> | Constructor<Array<Value>>,
+      optional: false,
+      multi: true,
+    },
+    options,
+  );
+}

package/src/injection/resolve-options.ts

@@ -0,0 +1,144 @@
+import type { BindingTag } from "#/core/tag";
+import type { Token } from "#/core/token";
+import type { Constructor, ResolveOptions } from "#/core/types";
+
+/**
+ * What one resolvable dependency declares.
+ *
+ * @remarks Both dependency sources — a constructor's `ParamMetadata` and a `toResolved`
+ * `InjectionDescriptor` — are this shape, which is why one resolve routine serves both.
+ *
+ * @since 0.5.0-canary.9
+ */
+export interface DependencySlot {
+  readonly token: Token<unknown> | Constructor;
+  readonly optional: boolean;
+  readonly multi: boolean;
+  readonly name?: string | undefined;
+  readonly tags?: ReadonlyArray<BindingTag> | undefined;
+}
+
+/**
+ * A request whose only criterion is a name — the shape the registry has a direct index for.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function isNameOnlyOptions(options: ResolveOptions): options is ResolveOptions & { name: string } {
+  return (
+    options.name !== undefined && options.tag === undefined && (options.tags === undefined || options.tags.length === 0)
+  );
+}
+
+/**
+ * The lone tag of a request that asks for exactly one, written either way — the shape the registry
+ * has a direct tag index for.
+ *
+ * @remarks Both spellings answer here, so the index is not something one of them silently misses.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function singleTagOnlyOf(options: ResolveOptions): BindingTag | undefined {
+  if (options.name !== undefined) {
+    return undefined;
+  }
+  const listed = options.tags;
+  const shorthand = options.tag;
+  if (shorthand !== undefined) {
+    // Both sources present means the request carries two tags, which no single-tag index can answer.
+    return listed === undefined || listed.length === 0 ? shorthand : undefined;
+  }
+  return listed !== undefined && listed.length === 1 ? listed[0] : undefined;
+}
+
+/** Shared core: build a ResolveOptions from already-normalised name + tags. */
+function buildOptions(
+  name: string | undefined,
+  tags: ReadonlyArray<BindingTag> | undefined,
+): ResolveOptions | undefined {
+  if (name === undefined && tags === undefined) {
+    return undefined;
+  }
+  const options: ResolveOptions = {};
+  if (name !== undefined) {
+    options.name = name;
+  }
+  if (tags !== undefined) {
+    options.tags = tags;
+  }
+  return options;
+}
+
+/**
+ * Builds a {@link ResolveOptions} safe for `exactOptionalPropertyTypes`:
+ * omits keys instead of assigning `undefined`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function injectionSlotToResolveOptions(
+  injectionSlot: Pick<DependencySlot, "name" | "tags">,
+): ResolveOptions | undefined {
+  return buildOptions(injectionSlot.name, injectionSlot.tags);
+}
+
+/** Where a slot's derived options are memoized, so the same object is handed out every resolve. */
+const MEMOIZED_RESOLVE_OPTIONS: unique symbol = Symbol("di:resolve-options");
+
+interface SlotWithMemoizedOptions {
+  [MEMOIZED_RESOLVE_OPTIONS]?: ResolveOptions;
+}
+
+/**
+ * The options a dependency resolves with — one object per slot, since a slot's criteria are fixed
+ * when it is declared.
+ *
+ * @remarks A slot carrying no criterion answers from its two fields, so the common shape never
+ * reaches the memo.
+ *
+ * @since 0.6.0
+ */
+export function resolveOptionsForSlot(injectionSlot: DependencySlot): ResolveOptions | undefined {
+  const { name, tags } = injectionSlot;
+  if (name === undefined && tags === undefined) {
+    return undefined;
+  }
+  const slot = injectionSlot as SlotWithMemoizedOptions;
+  const memoized = slot[MEMOIZED_RESOLVE_OPTIONS];
+  return memoized ?? memoizeResolveOptions(slot, name, tags);
+}
+
+/**
+ * Builds, freezes and stores a slot's options on first use.
+ *
+ * @remarks Frozen because one object answers every resolve of the slot and a constraint predicate is
+ * handed it. Split out for the `try`: in the caller it would cost the early return its inlining.
+ */
+function memoizeResolveOptions(
+  slot: SlotWithMemoizedOptions,
+  name: string | undefined,
+  tags: ReadonlyArray<BindingTag> | undefined,
+): ResolveOptions {
+  const built = Object.freeze(buildOptions(name, tags) as ResolveOptions);
+  try {
+    slot[MEMOIZED_RESOLVE_OPTIONS] = built;
+  } catch {
+    // A frozen slot rebuilds on every hop rather than throwing.
+  }
+  return built;
+}
+
+/**
+ * Resolve options derived from a binding slot (tags may be empty; omits when nothing to match).
+ *
+ * @remarks Takes the slot structurally rather than as `BindingSlot`, so the slot on a public
+ * `BindingSnapshot` — where `name` is an optional property, not a required one holding `undefined` —
+ * is accepted by the same call.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function bindingSlotToResolveOptions(bindingSlot: {
+  readonly name?: string | undefined;
+  readonly tags?: ReadonlyArray<BindingTag> | undefined;
+}): ResolveOptions | undefined {
+  const tags = bindingSlot.tags;
+  return buildOptions(bindingSlot.name, tags !== undefined && tags.length > 0 ? tags : undefined);
+}