bazis 0.96.1

package/core/di/extensions/options-reloadable.ts

@@ -0,0 +1,137 @@
+import { OptionsValidationError } from "../errors";
+import type { ServiceCollection } from "../ServiceCollection";
+import { createToken, type InjectionToken } from "../token";
+import type { ServiceResolver } from "../types";
+import { OPTIONS_STARTUP_VALIDATOR, type ValidatedOptionsConfig } from "./options";
+
+/** Unsubscribes an {@link OptionsMonitor.onChange} listener. Idempotent. */
+export interface OptionsChangeSubscription {
+  dispose(): void;
+}
+
+/**
+ * .NET `IOptionsMonitor<T>` analog: a singleton holding the always-current value,
+ * able to reload it on demand and notify subscribers. Reloads are explicit
+ * (`reload()`) — call it from a file watcher, admin endpoint, etc. — which keeps
+ * the design free of ambient config-change machinery.
+ */
+export interface OptionsMonitor<T> {
+  /** The latest validated value. */
+  readonly current: T;
+  /** Subscribes to value changes; dispose the result to unsubscribe. */
+  onChange(listener: (value: T) => void): OptionsChangeSubscription;
+  /**
+   * Re-runs `load`/`validate`. On success updates `current` and notifies
+   * listeners; on validation failure throws and keeps the last good value.
+   */
+  reload(): void;
+}
+
+/**
+ * .NET `IOptionsSnapshot<T>` analog: scoped, captured once per scope from the
+ * monitor's current value. Stable for the lifetime of the scope (e.g. a request)
+ * even if the monitor reloads mid-scope.
+ */
+export interface OptionsSnapshot<T> {
+  readonly value: T;
+}
+
+export function createOptionsMonitorToken<T>(name = "default"): InjectionToken<OptionsMonitor<T>> {
+  return createToken<OptionsMonitor<T>>(`IOptionsMonitor<${name}>`);
+}
+
+export function createOptionsSnapshotToken<T>(name = "default"): InjectionToken<OptionsSnapshot<T>> {
+  return createToken<OptionsSnapshot<T>>(`IOptionsSnapshot<${name}>`);
+}
+
+/** Token pair for a single reloadable options source. */
+export interface ReloadableOptionsTokens<T> {
+  readonly monitor: InjectionToken<OptionsMonitor<T>>;
+  readonly snapshot: InjectionToken<OptionsSnapshot<T>>;
+}
+
+export function createReloadableOptionsTokens<T>(name = "default"): ReloadableOptionsTokens<T> {
+  return {
+    monitor: createOptionsMonitorToken<T>(name),
+    snapshot: createOptionsSnapshotToken<T>(name),
+  };
+}
+
+class OptionsMonitorImpl<T> implements OptionsMonitor<T> {
+  private value: T;
+  private readonly listeners = new Set<(value: T) => void>();
+
+  public constructor(
+    private readonly config: ValidatedOptionsConfig<T>,
+    private readonly name: string,
+  ) {
+    this.value = this.loadValidated();
+  }
+
+  public get current(): T {
+    return this.value;
+  }
+
+  public onChange(listener: (value: T) => void): OptionsChangeSubscription {
+    this.listeners.add(listener);
+    return {
+      dispose: (): void => {
+        this.listeners.delete(listener);
+      },
+    };
+  }
+
+  public reload(): void {
+    // Validation runs before mutating state, so a bad reload leaves the last
+    // good value in place and never fires listeners with invalid data.
+    const next = this.loadValidated();
+    this.value = next;
+    for (const listener of this.listeners) {
+      listener(next);
+    }
+  }
+
+  private loadValidated(): T {
+    const value = this.config.load();
+    const issues = this.config.validate?.(value) ?? [];
+    if (issues.length > 0) {
+      throw new OptionsValidationError(issues.map((issue) => `${this.name}: ${issue}`));
+    }
+    return value;
+  }
+}
+
+/**
+ * Registers a reloadable options source: a singleton {@link OptionsMonitor} (the
+ * source of truth) and a scoped {@link OptionsSnapshot} read once per scope.
+ * Like `addValidatedOptions`, it participates in `validateOptionsOnStart` so a
+ * broken config fails fast on boot.
+ */
+export function addReloadableOptions<T>(
+  services: ServiceCollection,
+  tokens: ReloadableOptionsTokens<T>,
+  config: ValidatedOptionsConfig<T>,
+): void {
+  services.addSingleton({
+    provide: tokens.monitor,
+    useFactory: (): OptionsMonitor<T> => new OptionsMonitorImpl(config, tokens.monitor.description),
+    deps: [],
+  });
+
+  services.addScoped({
+    provide: tokens.snapshot,
+    // Captured once per scope from the singleton monitor's current value.
+    useFactory: (resolver: ServiceResolver): OptionsSnapshot<T> => ({ value: resolver.resolve(tokens.monitor).current }),
+    deps: [],
+    withResolver: true,
+  });
+
+  services.addTransient({
+    provide: OPTIONS_STARTUP_VALIDATOR,
+    useFactory: (resolver: ServiceResolver) => (): void => {
+      resolver.resolve(tokens.monitor);
+    },
+    deps: [],
+    withResolver: true,
+  });
+}

package/core/di/extensions/options.ts

@@ -0,0 +1,91 @@
+import { OptionsValidationError } from "../errors";
+import type { ServiceCollection } from "../ServiceCollection";
+import { createToken, type InjectionToken, type Token } from "../token";
+import type { ServiceResolver } from "../types";
+
+export interface Options<T> {
+  readonly value: T;
+}
+
+export function createOptionsToken<T>(name = "default"): InjectionToken<Options<T>> {
+  return createToken<Options<T>>(`IOptions<${name}>`);
+}
+
+export function addOptions<T>(services: ServiceCollection, token: InjectionToken<Options<T>>, value: T): void {
+  services.addSingleton({
+    provide: token,
+    useValue: { value },
+  });
+}
+
+export interface ValidatedOptionsConfig<T> {
+  /** Loads the raw options value (env vars, config file, constants). */
+  readonly load: () => T;
+  /** Returns a list of problems; empty list or `undefined` means the value is valid. */
+  readonly validate?: (value: T) => readonly string[] | undefined;
+}
+
+/**
+ * Startup validators registered by `addValidatedOptions`. Each one forces its
+ * options to load and validate; `validateOptionsOnStart` runs them all and
+ * aggregates every problem into a single `OptionsValidationError`.
+ */
+export const OPTIONS_STARTUP_VALIDATOR = createToken<() => void>("OptionsStartupValidator");
+
+/**
+ * .NET-style validated options: `load` runs lazily on first resolve, `validate`
+ * gates the value. For fail-fast behavior call `validateOptionsOnStart(container)`
+ * in your bootstrap (Application.start does it automatically).
+ */
+export function addValidatedOptions<T>(
+  services: ServiceCollection,
+  token: InjectionToken<Options<T>>,
+  config: ValidatedOptionsConfig<T>,
+): void {
+  services.addSingleton({
+    provide: token,
+    useFactory: (): Options<T> => {
+      const value = config.load();
+      const issues = config.validate?.(value) ?? [];
+      if (issues.length > 0) {
+        const name = token.description;
+        throw new OptionsValidationError(issues.map((issue) => `${name}: ${issue}`));
+      }
+      return { value };
+    },
+    deps: [],
+  });
+
+  services.addTransient({
+    provide: OPTIONS_STARTUP_VALIDATOR,
+    useFactory: (resolver: ServiceResolver) => (): void => {
+      resolver.resolve(token);
+    },
+    deps: [],
+    withResolver: true,
+  });
+}
+
+/**
+ * Fail-fast: resolves every validated options registration and throws one
+ * `OptionsValidationError` with all collected problems. Non-options errors
+ * (e.g. a throwing `load()`) are rethrown as-is.
+ */
+export function validateOptionsOnStart(provider: { resolveAll<T>(token: Token<T>): readonly T[] }): void {
+  const validators = provider.resolveAll(OPTIONS_STARTUP_VALIDATOR);
+  const issues: string[] = [];
+  for (let index = 0; index < validators.length; index += 1) {
+    try {
+      (validators[index] as () => void)();
+    } catch (error) {
+      if (error instanceof OptionsValidationError) {
+        issues.push(...error.issues);
+      } else {
+        throw error;
+      }
+    }
+  }
+  if (issues.length > 0) {
+    throw new OptionsValidationError(issues);
+  }
+}

package/core/di/extensions/service-provider-token.ts

@@ -0,0 +1,21 @@
+import { ServiceProvider } from "../ServiceProvider";
+import { createToken } from "../token";
+
+/**
+ * The container itself as an injectable service (.NET's IServiceProvider).
+ *
+ * Registered automatically by `createContainer` as a global provider, so any
+ * service can receive the root container — primarily to create per-request
+ * scopes (`provider.createScope()`) from infrastructure like the HTTP server.
+ *
+ * Resolve it sparingly: business services should depend on their actual
+ * dependencies, not on the container (service-locator anti-pattern).
+ */
+export const SERVICE_PROVIDER = createToken<ServiceProvider>("IServiceProvider");
+
+/**
+ * Internal alias for the canonical class token used by generated constructor
+ * dependencies. Name-based dependencies resolve this same token, so no
+ * second token with the debug name `ServiceProvider` competes with the class.
+ */
+export const SERVICE_PROVIDER_BY_TYPE = ServiceProvider;

package/core/di/index.ts

@@ -0,0 +1,97 @@
+export type { BuildServiceProviderOptions, ServiceKey, ServiceResolver } from "./types";
+export { ServiceCollection } from "./ServiceCollection";
+export { ServiceProvider } from "./ServiceProvider";
+export { ServiceScope } from "./ServiceScope";
+export { DiContainer } from "./container";
+export * from "./extensions";
+export {
+  AmbiguousNamedDependencyError,
+  AsyncResolutionRequiredError,
+  CircularDependencyError,
+  ClassDependenciesMismatchError,
+  DiError,
+  InvalidProviderError,
+  ModuleEncapsulationError,
+  ModuleOwnedProviderConflictError,
+  NamedDependencyNotFoundError,
+  OptionsValidationError,
+  ProviderNotFoundError,
+  ScopeDisposedError,
+  ScopedServiceFromRootError,
+  ServiceValidationError,
+} from "./errors";
+export {
+  createContainer,
+  collectModuleControllers,
+  collectModuleConfigs,
+  collectModuleUiProfiles,
+  Global,
+  markGlobal,
+  Module,
+  DI,
+  registerModuleMetadataExpander,
+  registerModuleOwnedContributionValidator,
+  registerModuleOwnedProviderContributor,
+  expandModuleMetadata,
+  createModuleOwnedMetadataChannel,
+  createModuleOwnedProviderChannel,
+  scoped,
+  singleton,
+  singletonAsyncFactory,
+  singletonAsyncFactoryWithResolver,
+  singletonFactory,
+  singletonFactoryWithResolver,
+  singletonValue,
+  transient,
+  type DiRegistrar,
+  type ModuleConfig,
+  type ModuleExport,
+  type ModuleMetadataExpander,
+  type ModuleOwnedContributionChannel,
+  type ModuleOwnedContributionSnapshot,
+  type ModuleOwnedValidationSnapshot,
+  type ModuleOwnedContributionValidator,
+  type ModuleOwnedMetadataChannel,
+  type ModuleOwnedMetadataContribution,
+  type ModuleOwnedProviderActivation,
+  type ModuleOwnedProviderChannel,
+  type ModuleOwnedProviderContribution,
+  type ModuleOwnedProviderContributionContext,
+  type ModuleOwnedProviderContributor,
+  type BazisModule,
+  type BazisModuleMetadata,
+  type BazisModuleRef,
+} from "./module";
+export {
+  CLASS_PROVIDER_HOOK,
+  type ClassProviderHook,
+  type ClassProviderRegistration,
+} from "./module/classProviderHooks";
+export {
+  registerNamedDependencyEncapsulationHook,
+  type NamedDependencyEncapsulationContext,
+  type NamedDependencyEncapsulationHook,
+} from "./module/encapsulationHooks";
+export {
+  createOpenGenericTokenFamily,
+  createToken,
+  type Class,
+  type InjectionToken,
+  type OpenGenericTokenFamily,
+  type Token,
+} from "./token";
+export { ProviderDefinition, keyedDependency, lazyDependency, namedDependency } from "./provider";
+export type {
+  AsyncFactoryProvider,
+  ClassProvider,
+  FactoryProvider,
+  KeyedDependency,
+  Lazy,
+  LazyDependency,
+  NamedDependency,
+  Provider,
+  ProviderDependencyList,
+  ProviderLifetime,
+  ResolvedDeps,
+  ValueProvider,
+} from "./provider";

package/core/di/internal/GraphValidator.ts

@@ -0,0 +1,119 @@
+import { ServiceValidationError } from "../errors";
+import { isLazyDependency } from "../provider";
+import type {
+  KeyedDependency,
+  NamedDependency,
+  Provider,
+  ProviderDependencyList,
+  ProviderLifetime,
+} from "../provider";
+import { tokenToDebugName, type Token } from "../token";
+import type { ServiceKey } from "../types";
+import type { ServiceRegistration } from "./ServiceRegistration";
+
+/**
+ * Everything the build-time graph validator needs from the container, exposed as
+ * a narrow context so {@link GraphValidator} stays independent of the container's
+ * private resolution internals (and unit-testable on its own).
+ */
+export interface GraphValidationContext {
+  readonly validateScopes: boolean;
+  registrationGroups(): Iterable<readonly ServiceRegistration[]>;
+  /** Materializes every open generic against the registered tokens, collecting factory failures. */
+  eagerlyMaterializeOpenGenerics(issues: Set<string>): void;
+  dependencies(provider: Provider<unknown>): ProviderDependencyList;
+  /** Constructor arity vs declared deps for class providers; `undefined` for non-class providers. */
+  classShape(provider: Provider<unknown>): { readonly required: number; readonly declared: number } | undefined;
+  describeDependency(
+    dependency: Token<unknown> | KeyedDependency<unknown> | NamedDependency<unknown>,
+  ): { readonly token: Token<unknown>; readonly key: ServiceKey | undefined };
+  findRegistration(token: Token<unknown>, key: ServiceKey | undefined): ServiceRegistration | undefined;
+}
+
+/**
+ * Static (build-time) graph validation: detects cycles, missing dependencies,
+ * captive dependencies (singleton -> scoped) and class arity mismatches, then
+ * reports every problem at once via {@link ServiceValidationError}. Runs once on
+ * `validateOnBuild`; the resolution hot path never touches this code.
+ */
+export class GraphValidator {
+  public constructor(private readonly context: GraphValidationContext) {}
+
+  public validate(): void {
+    const issues = new Set<string>();
+    this.context.eagerlyMaterializeOpenGenerics(issues);
+    for (const registrations of this.context.registrationGroups()) {
+      for (let index = 0; index < registrations.length; index += 1) {
+        const registration = registrations[index] as ServiceRegistration;
+        this.validateRegistration(registration, registration.lifetime, [], new Set<number>(), issues);
+      }
+    }
+
+    if (issues.size > 0) {
+      throw new ServiceValidationError([...issues]);
+    }
+  }
+
+  private validateRegistration(
+    registration: ServiceRegistration,
+    rootLifetime: ProviderLifetime,
+    tokenPath: Token<unknown>[],
+    registrationPath: Set<number>,
+    issues: Set<string>,
+  ): void {
+    if (registrationPath.has(registration.id)) {
+      const cyclePath = [...tokenPath, registration.token].map((token) => tokenToDebugName(token)).join(" -> ");
+      issues.add(`Cycle detected: ${cyclePath}`);
+      return;
+    }
+
+    const shape = this.context.classShape(registration.provider);
+    if (shape && shape.required > shape.declared) {
+      issues.add(
+        `Class provider "${tokenToDebugName(registration.token)}" requires at least ${shape.required} constructor deps, but only ${shape.declared} declared.`,
+      );
+    }
+
+    const deps = this.context.dependencies(registration.provider);
+    if (deps.length === 0) {
+      return;
+    }
+
+    registrationPath.add(registration.id);
+    tokenPath.push(registration.token);
+    try {
+      for (let index = 0; index < deps.length; index += 1) {
+        const dependency = deps[index];
+        if (dependency === undefined) {
+          continue;
+        }
+        const isLazy = isLazyDependency(dependency);
+        const descriptor = this.context.describeDependency(isLazy ? dependency.inner : dependency);
+        const depRegistration = this.context.findRegistration(descriptor.token, descriptor.key);
+        if (!depRegistration) {
+          issues.add(
+            `Missing dependency "${tokenToDebugName(descriptor.token)}" for "${tokenToDebugName(registration.token)}"`,
+          );
+          continue;
+        }
+
+        if (this.context.validateScopes && rootLifetime === "singleton" && depRegistration.lifetime === "scoped") {
+          issues.add(
+            `Singleton "${tokenToDebugName(registration.token)}" depends on scoped "${tokenToDebugName(descriptor.token)}"`,
+          );
+        }
+
+        // Lazy edges defer creation to first access, so they cannot deadlock
+        // construction: validate existence above, but do not traverse them.
+        if (isLazy) {
+          continue;
+        }
+
+        this.validateRegistration(depRegistration, rootLifetime, tokenPath, registrationPath, issues);
+      }
+    } finally {
+      tokenPath.pop();
+      registrationPath.delete(registration.id);
+    }
+  }
+}

package/core/di/internal/HostedServicePlan.ts

@@ -0,0 +1,158 @@
+import type { HostedService, HostedServicePlanValidator } from "../extensions/hosted-service";
+
+/** Internal bridge: DI knows plan composition, never a particular wrapper class. */
+export interface HostedServicePlanAdmission {
+  readonly phase: number;
+  replace(candidate: HostedService, signal?: AbortSignal): Promise<void>;
+}
+
+interface HostedServiceWrapper {
+  readonly explicitPhase?: number;
+  prepare(): HostedService;
+  bind(admission: HostedServicePlanAdmission): void;
+}
+
+const wrappers = new WeakMap<HostedService, HostedServiceWrapper>();
+const owners = new WeakMap<HostedService, HostedServicePlan>();
+
+export function registerHostedServiceWrapper(service: HostedService, wrapper: HostedServiceWrapper): void {
+  wrappers.set(service, wrapper);
+}
+
+interface PlanNode {
+  readonly service: HostedService;
+  readonly phase: number;
+  readonly wrapper?: HostedServiceWrapper;
+  readonly child?: PlanNode;
+}
+
+export function prepareHostedServicePlan(services: readonly HostedService[], signal?: AbortSignal): void | Promise<void> {
+  signal?.throwIfAborted();
+  if (!services.some(service => wrappers.has(service) || service.planValidator !== undefined)) return;
+  return new HostedServicePlan(services, signal).admit(signal);
+}
+
+/** One host run owns its concrete identities and serializes whole-plan replacements. */
+class HostedServicePlan {
+  private roots: readonly PlanNode[];
+  private readonly phases: readonly number[];
+  private replacement: Promise<void> = Promise.resolve();
+
+  constructor(services: readonly HostedService[], signal?: AbortSignal) {
+    this.roots = services.map(service => materialize(service, new Set(), signal));
+    this.phases = this.roots.map(node => node.phase);
+  }
+
+  async admit(signal?: AbortSignal): Promise<void> {
+    await this.validate(this.roots, signal);
+    signal?.throwIfAborted();
+    this.bind();
+  }
+
+  private replace(owner: HostedService, candidate: HostedService, signal?: AbortSignal): Promise<void> {
+    const replacing = this.replacement.then(async () => {
+      signal?.throwIfAborted();
+      this.assertOwner(owner);
+      const child = materialize(candidate, new Set([owner]), signal);
+      const roots = this.roots.map(node => replaceChild(node, owner, child));
+      if (roots.some((node, index) => node.phase !== this.phases[index])) {
+        throw new Error("Hosted service retry cannot change the admitted startup phase.");
+      }
+      await this.validate(roots, signal);
+      signal?.throwIfAborted();
+      this.assertOwner(owner);
+      // No await between the last admission check and publication.
+      this.roots = roots;
+      this.bind();
+    });
+    this.replacement = replacing.catch(() => {});
+    return replacing;
+  }
+
+  private assertOwner(owner: HostedService): void {
+    if (owners.get(owner) !== this || !nodesOf(this.roots).some(node => node.service === owner && node.wrapper)) {
+      throw new Error("Hosted service retry belongs to an inactive plan wrapper.");
+    }
+  }
+
+  private async validate(roots: readonly PlanNode[], signal?: AbortSignal): Promise<void> {
+    const nodes = nodesOf(roots);
+    const seen = new Set<HostedService>();
+    for (const node of nodes) {
+      if (seen.has(node.service)) throw new Error("Hosted service plan contains a duplicate service identity.");
+      seen.add(node.service);
+    }
+    const plan = Object.freeze(roots.map(concrete));
+    const validators = new Set<HostedServicePlanValidator>();
+    for (const service of plan) if (service.planValidator !== undefined) validators.add(service.planValidator);
+    if (validators.size > 0) {
+      for (const node of nodes) {
+        if (node.wrapper && node.phase !== (concrete(node).phase ?? 0)) {
+          throw new Error("Supervised hosted phase conflicts with the concrete service phase required by plan validators.");
+        }
+      }
+    }
+    for (const validator of validators) {
+      signal?.throwIfAborted();
+      await awaitValidation(validator.validate(plan, signal), signal);
+    }
+    signal?.throwIfAborted();
+  }
+
+  private bind(): void {
+    for (const node of nodesOf(this.roots)) {
+      if (!node.wrapper) continue;
+      owners.set(node.service, this);
+      node.wrapper.bind({ phase: node.phase, replace: (candidate, signal) => this.replace(node.service, candidate, signal) });
+    }
+  }
+}
+
+function materialize(service: HostedService, ancestors: Set<HostedService>, signal?: AbortSignal): PlanNode {
+  signal?.throwIfAborted();
+  if (ancestors.has(service)) throw new Error("Hosted service wrapper factory cycle.");
+  const wrapper = wrappers.get(service);
+  if (!wrapper) return { service, phase: service.phase ?? 0 };
+  ancestors.add(service);
+  try {
+    const child = materialize(wrapper.prepare(), ancestors, signal);
+    return { service, wrapper, child, phase: wrapper.explicitPhase ?? child.phase };
+  } finally {
+    ancestors.delete(service);
+  }
+}
+
+function concrete(node: PlanNode): HostedService {
+  return node.child ? concrete(node.child) : node.service;
+}
+
+function nodesOf(roots: readonly PlanNode[]): PlanNode[] {
+  const nodes: PlanNode[] = [];
+  for (const root of roots) {
+    for (let node: PlanNode | undefined = root; node !== undefined; node = node.child) nodes.push(node);
+  }
+  return nodes;
+}
+
+function replaceChild(node: PlanNode, owner: HostedService, replacement: PlanNode): PlanNode {
+  if (!node.wrapper || !node.child) return node;
+  const child = node.service === owner ? replacement : replaceChild(node.child, owner, replacement);
+  return child === node.child ? node : { ...node, child, phase: node.wrapper.explicitPhase ?? child.phase };
+}
+
+async function awaitValidation(value: void | Promise<void>, signal?: AbortSignal): Promise<void> {
+  if (!signal) return await value;
+  let onAbort: (() => void) | undefined;
+  try {
+    await Promise.race([
+      value,
+      new Promise<never>((_resolve, reject) => {
+        onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted) onAbort();
+      }),
+    ]);
+  } finally {
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}

package/core/di/internal/NamedTokenIndex.ts

@@ -0,0 +1,55 @@
+import { AmbiguousNamedDependencyError } from "../errors";
+import { tokenToDebugName, type Token } from "../token";
+
+const AMBIGUOUS = Symbol("bazis.di.ambiguous-name");
+
+/**
+ * Maps a token's debug name (`createToken("X")` description or class name) to its
+ * token, powering name-based auto deps. Built lazily on first lookup from the
+ * full token set; tokens added afterwards (materialized open generics) are
+ * indexed incrementally. Distinct tokens sharing a name resolve to an ambiguity
+ * marker so a name lookup fails loudly instead of silently picking one.
+ */
+export class NamedTokenIndex {
+  private cache: Map<string, Token<unknown> | typeof AMBIGUOUS> | undefined;
+
+  public constructor(private readonly enumerateTokens: () => Iterable<Token<unknown>>) {}
+
+  public lookup(name: string): Token<unknown> | undefined {
+    if (!this.cache) {
+      this.cache = new Map();
+      for (const token of this.enumerateTokens()) {
+        this.indexInternal(token);
+      }
+    }
+
+    const found = this.cache.get(name);
+    if (found === AMBIGUOUS) {
+      throw new AmbiguousNamedDependencyError(name);
+    }
+    return found;
+  }
+
+  public index(token: Token<unknown>): void {
+    // Before the first lookup the cache is rebuilt from scratch, so eager
+    // indexing would be wasted work — defer until the cache exists.
+    if (!this.cache) {
+      return;
+    }
+    this.indexInternal(token);
+  }
+
+  private indexInternal(token: Token<unknown>): void {
+    const cache = this.cache;
+    if (!cache) {
+      return;
+    }
+    const name = tokenToDebugName(token);
+    const existing = cache.get(name);
+    if (existing === undefined) {
+      cache.set(name, token);
+    } else if (existing !== token) {
+      cache.set(name, AMBIGUOUS);
+    }
+  }
+}

package/core/di/internal/OpenGenericRegistration.ts

@@ -0,0 +1,14 @@
+import type { Provider, ProviderLifetime } from "../provider";
+import type { OpenGenericTokenFamily, Token } from "../token";
+import type { ServiceKey } from "../types";
+
+export type OpenGenericProviderFactory = (argument: Token<unknown>) => Provider<unknown>;
+
+export class OpenGenericRegistration {
+  public constructor(
+    public readonly family: OpenGenericTokenFamily<unknown, unknown>,
+    public readonly providerFactory: OpenGenericProviderFactory,
+    public readonly lifetime: ProviderLifetime,
+    public readonly key?: ServiceKey,
+  ) {}
+}