@codefast/di 0.5.0-canary.6 → 0.5.0-canary.8

package/src/resolution/diagnostics.ts

@@ -0,0 +1,43 @@
+/**
+ * Internal seam letting tests assert that an optimization is *active*, not merely that the result
+ * is correct.
+ *
+ * @remarks Timing belongs in the benchmark, which needs a quiet machine and twenty minutes; these
+ * are structural counts, so CI can hold the invariants that make the benchmark fast. Reached
+ * through a symbol from a module the package does not publish, so it is not public API.
+ */
+
+/**
+ * Key for the diagnostics accessor on a container.
+ *
+ * @remarks A symbol rather than a method name, so it cannot collide with the public surface or be
+ * reached by anyone who has not imported this module.
+ *
+ * @since 0.5.0-canary.8
+ */
+export const RESOLUTION_DIAGNOSTICS: unique symbol = Symbol("di:resolution-diagnostics");
+
+/**
+ * Structural facts about a container's resolution caches.
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface ResolutionDiagnostics {
+  /** Bindings with a compiled instantiation plan. */
+  readonly compiledPlanCount: number;
+  /** Contexts held by the depth-indexed sync pool. */
+  readonly syncContextPoolSize: number;
+  /** Contexts returned to the async chain pool and available for reuse. */
+  readonly asyncContextPoolSize: number;
+  /** Deferred collaborators this container has had to build. */
+  readonly builtSubsystems: ReadonlyArray<string>;
+}
+
+/**
+ * A container that can report on its resolution caches.
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface DiagnosableContainer {
+  [RESOLUTION_DIAGNOSTICS](): ResolutionDiagnostics;
+}

package/src/{environment.ts → resolution/environment.ts}

@@ -1,4 +1,4 @@
-import type { Container } from "#/container";
+import type { Container } from "#/container/container";
 import type { Token } from "#/token";
 import type {
   BindingIdentifier,
@@ -13,18 +13,18 @@ import type {
 
 // ── Active container ──────────────────────────────────────────────────────────
 
-let _activeContainer: Container | undefined;
+let activeContainer: Container | undefined;
 
 /**
  * @since 0.3.16-canary.0
  */
 export function runWithContainer<Result>(container: Container, fn: () => Result): Result {
-  const prev = _activeContainer;
-  _activeContainer = container;
+  const prev = activeContainer;
+  activeContainer = container;
   try {
     return fn();
   } finally {
-    _activeContainer = prev;
+    activeContainer = prev;
   }
 }
 
@@ -32,7 +32,7 @@ export function runWithContainer<Result>(container: Container, fn: () => Result)
  * @since 0.3.16-canary.0
  */
 export function getActiveContainer(): Container | undefined {
-  return _activeContainer;
+  return activeContainer;
 }
 
 // ── ResolutionContext implementation ──────────────────────────────────────────
@@ -56,6 +56,7 @@ export interface ResolverCallbacks {
     token: Token<Value> | Constructor<Value>,
     resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
+    callerContext?: DefaultResolutionContext,
   ): Promise<Value>;
   resolveAsync<const Value>(
     token: Token<Value> | Constructor<Value>,
@@ -93,10 +94,10 @@ export interface ResolverCallbacks {
  * @since 0.3.16-canary.0
  */
 export class DefaultResolutionContext implements ResolutionContext {
-  private _resolver: ResolverCallbacks;
-  private _resolutionPath: Array<string>;
-  private _resolutionStack: Array<ResolutionFrame>;
-  private _currentOptions: ResolveOptions | undefined;
+  #resolver: ResolverCallbacks;
+  #resolutionPath: Array<string>;
+  #resolutionStack: Array<ResolutionFrame>;
+  #currentOptions: ResolveOptions | undefined;
 
   constructor(
     resolver: ResolverCallbacks,
@@ -104,19 +105,44 @@ export class DefaultResolutionContext implements ResolutionContext {
     resolutionStack: Array<ResolutionFrame>,
     currentOptions: ResolveOptions | undefined,
   ) {
-    this._resolver = resolver;
-    this._resolutionPath = resolutionPath;
-    this._resolutionStack = resolutionStack;
-    this._currentOptions = currentOptions;
+    this.#resolver = resolver;
+    this.owner = resolver;
+    this.#resolutionPath = resolutionPath;
+    this.#resolutionStack = resolutionStack;
+    this.#currentOptions = currentOptions;
   }
 
-  private _graph: ConstraintContext | undefined;
+  #graph: ConstraintContext | undefined;
+
+  /**
+   * The unwind callback shared by every level of the async chain this context serves.
+   *
+   * @remarks A plain field, not a lazy accessor — a getter taking a factory would allocate that
+   * factory on every level, which is the allocation this exists to avoid.
+   */
+  chainSettle: (() => void) | undefined;
+
+  /**
+   * How many levels of the async chain are still in flight on this context.
+   *
+   * @remarks The chain's first level acquires the context and every level increments; the last
+   * one to settle returns it to the resolver's pool. Counting here rather than on the resolver
+   * is what lets two concurrent chains run without a shared counter to get wrong.
+   */
+  chainLevels = 0;
+
+  /**
+   * The resolver this context speaks to — an inner async level checks it before reusing this.
+   *
+   * @remarks A field, not a method, because the check runs on every hop of every chain.
+   */
+  owner: ResolverCallbacks;
 
   get graph(): ConstraintContext {
-    if (this._graph === undefined) {
-      this._graph = new DefaultConstraintContext(this._resolutionPath, this._resolutionStack, this._currentOptions);
+    if (this.#graph === undefined) {
+      this.#graph = new DefaultConstraintContext(this.#resolutionPath, this.#resolutionStack, this.#currentOptions);
     }
-    return this._graph;
+    return this.#graph;
   }
 
   reset(
@@ -125,47 +151,51 @@ export class DefaultResolutionContext implements ResolutionContext {
     resolutionStack: Array<ResolutionFrame>,
     currentOptions: ResolveOptions | undefined,
   ): void {
-    this._resolver = resolver;
-    this._resolutionPath = resolutionPath;
-    this._resolutionStack = resolutionStack;
-    this._currentOptions = currentOptions;
-    this._graph = undefined;
+    this.#resolver = resolver;
+    this.owner = resolver;
+    this.#resolutionPath = resolutionPath;
+    this.#resolutionStack = resolutionStack;
+    this.#currentOptions = currentOptions;
+    this.#graph = undefined;
+    this.chainSettle = undefined;
+    this.chainLevels = 0;
   }
 
   resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
     if (options === undefined) {
-      return this._resolver.resolveFromContext(token, this._resolutionPath, this._resolutionStack);
+      return this.#resolver.resolveFromContext(token, this.#resolutionPath, this.#resolutionStack);
     }
-    return this._resolver.resolve(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolve(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
     if (options === undefined) {
-      return this._resolver.resolveAsyncFromContext(token, this._resolutionPath, this._resolutionStack);
+      // Hand the callee this context: an inner level of the same chain reuses it as-is.
+      return this.#resolver.resolveAsyncFromContext(token, this.#resolutionPath, this.#resolutionStack, this);
     }
-    return this._resolver.resolveAsync(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveAsync(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
-    return this._resolver.resolveOptional(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveOptional(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveOptionalAsync<const Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Value | undefined> {
-    return this._resolver.resolveOptionalAsync(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveOptionalAsync(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
-    return this._resolver.resolveAll(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveAll(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveAllAsync<const Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Array<Value>> {
-    return this._resolver.resolveAllAsync(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveAllAsync(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 }
 
@@ -186,13 +216,13 @@ class DefaultConstraintContext implements ConstraintContext {
     this.currentResolveOptions = currentResolveOptions;
   }
 
-  private _ancestors: ReadonlyArray<ResolutionFrame> | undefined;
+  #ancestors: ReadonlyArray<ResolutionFrame> | undefined;
 
   get ancestors(): ReadonlyArray<ResolutionFrame> {
-    if (this._ancestors === undefined) {
-      this._ancestors = this.resolutionStack.length > 1 ? this.resolutionStack.slice(0, -1) : [];
+    if (this.#ancestors === undefined) {
+      this.#ancestors = this.resolutionStack.length > 1 ? this.resolutionStack.slice(0, -1) : [];
     }
-    return this._ancestors;
+    return this.#ancestors;
   }
 }
 

package/src/resolution/instantiation-plan.ts

@@ -0,0 +1,292 @@
+/**
+ * Compiles a transient class or resolved-factory binding into a nested-constructor closure.
+ *
+ * @see `ARCHITECTURE.md` — the escape contract every dependency the compiler cannot inline must honour.
+ */
+import type { Binding } from "#/binding";
+import { NO_INSTANCE } from "#/binding";
+import type { ConstructorInvocation } from "#/constructor-type";
+import type { InjectionDescriptor } from "#/decorators/inject";
+import { AsyncResolutionError } from "#/errors";
+import type { ConstructorMetadata } from "#/metadata/metadata-types";
+import { injectionSlotToResolveOptions } from "#/resolution/resolve-options";
+import type { Token } from "#/token";
+import { tokenName } from "#/token";
+import type { BindingScope, Constructor, ResolutionFrame, ResolveOptions } from "#/types";
+
+// Past this depth a dependency escapes to the runtime path rather than inlining further —
+// compiled closures nest one JS frame per level, and pathological graphs are the runtime's job.
+const PLAN_DEPTH_LIMIT = 32;
+
+/**
+ * Compilation asked to retry later (class lifecycle metadata not discovered yet).
+ *
+ * @since 0.5.0-canary.7
+ */
+export const PLAN_RETRY: unique symbol = Symbol("di:plan-retry");
+
+/**
+ * A compiled plan, `null` for "not plannable under the current cache versions",
+ * or {@link PLAN_RETRY} when a first runtime resolve must discover metadata first.
+ *
+ * @since 0.5.0-canary.7
+ */
+export type InstantiationPlanCompileResult = (() => unknown) | null | typeof PLAN_RETRY;
+
+/**
+ * What compiling one *dependency* can yield.
+ *
+ * @remarks No `null`: a dependency escapes rather than failing, so "no plan" is only ever a
+ * verdict on a plan's root.
+ */
+type DependencyCompileResult = (() => unknown) | typeof PLAN_RETRY;
+
+/**
+ * A dependency's terminal binding — all a compiled thunk needs.
+ *
+ * @since 0.5.0-canary.7
+ */
+export interface InstantiationPlanDependencyEntry {
+  readonly binding: Binding;
+}
+
+/**
+ * Everything the compiler needs from its resolver, expressed as behavior so the
+ * compiler stays independently testable and free of resolver internals.
+ *
+ * @since 0.5.0-canary.7
+ */
+export interface InstantiationPlanHost {
+  hasActivationHandlers(token: Token<unknown> | Constructor): boolean;
+  /** Cached postConstruct presence — `undefined` until a runtime resolve discovers it. */
+  knownPostConstruct(target: Constructor): boolean | undefined;
+  needsActiveContainer(target: Constructor): boolean;
+  getConstructorMetadata(target: Constructor): ConstructorMetadata | undefined;
+  /** Options-less lookup with alias hops folded; `null` when the fast lane can't answer. */
+  lookupDependencyEntry(token: Token<unknown> | Constructor): InstantiationPlanDependencyEntry | null;
+  /** The frame the interpreted path pushes for this binding, so escapes can replay it. */
+  getResolutionFrame(binding: Binding): ResolutionFrame;
+  /** Runtime resolve for an escaped dependency, seeded with the ancestors above it. */
+  resolveEscaped(
+    token: Token<unknown> | Constructor,
+    options: ResolveOptions | undefined,
+    arity: EscapeArity,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): unknown;
+}
+
+/**
+ * Which resolve an escaped dependency replays — mirrors how the interpreted path dispatches
+ * a constructor param.
+ *
+ * @since 0.5.0-canary.8
+ */
+export type EscapeArity = "all" | "optional" | "single";
+
+/**
+ * @since 0.3.16-canary.1
+ */
+export class InstantiationPlanCompiler {
+  readonly #host: InstantiationPlanHost;
+
+  constructor(host: InstantiationPlanHost) {
+    this.#host = host;
+  }
+
+  compile(binding: Binding & { kind: "class" | "resolved" }): InstantiationPlanCompileResult {
+    return binding.kind === "class"
+      ? this.#compileClassPlan(binding, new Set(), 0, [])
+      : this.#compileResolvedPlan(binding, new Set(), 0, []);
+  }
+
+  /**
+   * Re-entry into the runtime resolver for a dependency the plan can't see through.
+   *
+   * The ancestors are fixed at compile time, so the seeds are built once; each call copies
+   * them because the resolver pushes and pops on the arrays it is given.
+   */
+  #compileEscapeThunk(
+    token: Token<unknown> | Constructor,
+    ancestors: ReadonlyArray<Binding>,
+    arity: EscapeArity = "single",
+    options?: ResolveOptions,
+  ): () => unknown {
+    const host = this.#host;
+    const frames = ancestors.map((ancestor) => host.getResolutionFrame(ancestor));
+    const names = frames.map((frame) => frame.tokenName);
+    return () => host.resolveEscaped(token, options, arity, [...names], [...frames]);
+  }
+
+  // A resolved binding declares its deps as explicit descriptors — same rules as
+  // class params, with the factory call (and its sync-only check) in place of `new`.
+  #compileResolvedPlan(
+    binding: Binding & { kind: "resolved" },
+    compileStack: Set<Binding["id"]>,
+    depth: number,
+    ancestors: ReadonlyArray<Binding>,
+  ): InstantiationPlanCompileResult {
+    if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding.token)) {
+      return null;
+    }
+    const factory = binding.factory;
+    const tokenDisplayName = tokenName(binding.token);
+    const depThunks = new Array<() => unknown>(binding.deps.length);
+    const depAncestors = [...ancestors, binding];
+    compileStack.add(binding.id);
+    try {
+      for (let index = 0; index < binding.deps.length; index += 1) {
+        const thunk = this.#compileInjectionThunk(binding.deps[index]!, compileStack, depth, depAncestors);
+        if (thunk === PLAN_RETRY) {
+          return thunk;
+        }
+        depThunks[index] = thunk;
+      }
+    } finally {
+      compileStack.delete(binding.id);
+    }
+    return () => {
+      const factoryResult = factory(...depThunks.map((thunk) => thunk()));
+      if (factoryResult instanceof Promise) {
+        throw new AsyncResolutionError(tokenDisplayName, tokenDisplayName);
+      }
+      return factoryResult;
+    };
+  }
+
+  /**
+   * One dependency of a plan node — a constructor param or a `toResolved` descriptor.
+   *
+   * @remarks Anything but a plain required single dependency escapes to the runtime path.
+   */
+  #compileInjectionThunk(
+    descriptor: InjectionDescriptor,
+    compileStack: Set<Binding["id"]>,
+    depth: number,
+    ancestors: ReadonlyArray<Binding>,
+  ): DependencyCompileResult {
+    const token = descriptor.token as Token<unknown> | Constructor;
+    const options = injectionSlotToResolveOptions(descriptor);
+    if (descriptor.multi) {
+      return this.#compileEscapeThunk(token, ancestors, "all", options);
+    }
+    if (descriptor.optional) {
+      return this.#compileEscapeThunk(token, ancestors, "optional", options);
+    }
+    if (options !== undefined) {
+      return this.#compileEscapeThunk(token, ancestors, "single", options);
+    }
+    const entry = this.#host.lookupDependencyEntry(token);
+    if (entry === null) {
+      return this.#compileEscapeThunk(token, ancestors);
+    }
+    return this.#compileDepThunk(entry, compileStack, depth, ancestors);
+  }
+
+  #compileClassPlan(
+    binding: Binding & { kind: "class" },
+    compileStack: Set<Binding["id"]>,
+    depth: number,
+    ancestors: ReadonlyArray<Binding>,
+  ): InstantiationPlanCompileResult {
+    if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding.token)) {
+      return null;
+    }
+    const target = binding.target;
+    const hasPostConstruct = this.#host.knownPostConstruct(target);
+    if (hasPostConstruct === undefined) {
+      return PLAN_RETRY;
+    }
+    if (hasPostConstruct || this.#host.needsActiveContainer(target)) {
+      return null;
+    }
+    const invokable = target as ConstructorInvocation;
+    const meta = this.#host.getConstructorMetadata(target);
+    if (meta === undefined) {
+      // Metadata-less classes with required params throw on the runtime path — keep them there.
+      return target.length === 0 ? () => new invokable() : null;
+    }
+    const params = meta.params;
+    if (params.length === 0) {
+      return () => new invokable();
+    }
+    const depThunks = new Array<() => unknown>(params.length);
+    const depAncestors = [...ancestors, binding];
+    compileStack.add(binding.id);
+    try {
+      for (let index = 0; index < params.length; index += 1) {
+        const thunk = this.#compileInjectionThunk(params[index]!, compileStack, depth, depAncestors);
+        if (thunk === PLAN_RETRY) {
+          return thunk;
+        }
+        depThunks[index] = thunk;
+      }
+    } finally {
+      compileStack.delete(binding.id);
+    }
+    switch (depThunks.length) {
+      case 1: {
+        const dep0 = depThunks[0]!;
+        return () => new invokable(dep0());
+      }
+      case 2: {
+        const dep0 = depThunks[0]!;
+        const dep1 = depThunks[1]!;
+        return () => new invokable(dep0(), dep1());
+      }
+      case 3: {
+        const dep0 = depThunks[0]!;
+        const dep1 = depThunks[1]!;
+        const dep2 = depThunks[2]!;
+        return () => new invokable(dep0(), dep1(), dep2());
+      }
+      default:
+        return () => new invokable(...depThunks.map((thunk) => thunk()));
+    }
+  }
+
+  #compileDepThunk(
+    entry: InstantiationPlanDependencyEntry,
+    compileStack: Set<Binding["id"]>,
+    depth: number,
+    ancestors: ReadonlyArray<Binding>,
+  ): DependencyCompileResult {
+    const { binding } = entry;
+    if (binding.kind === "constant" && binding.onActivation === undefined) {
+      if (!this.#host.hasActivationHandlers(binding.token)) {
+        const value = binding.value;
+        return () => value;
+      }
+    }
+    const scope = (binding as Binding & { scope: BindingScope }).scope ?? "transient";
+    if (scope === "singleton") {
+      // Cached-singleton read; the first materialization escapes so it sees the same ancestors
+      // (and therefore the same cycle detection) the interpreted path would have built.
+      const escape = this.#compileEscapeThunk(binding.token, ancestors);
+      const singletonBinding = binding;
+      return () => {
+        const cached = singletonBinding.instance;
+        return cached === NO_INSTANCE ? escape() : cached;
+      };
+    }
+    if (
+      scope === "transient" &&
+      binding.kind === "class" &&
+      depth < PLAN_DEPTH_LIMIT &&
+      !compileStack.has(binding.id)
+    ) {
+      const inlined = this.#compileClassPlan(
+        binding as Binding & { kind: "class" },
+        compileStack,
+        depth + 1,
+        ancestors,
+      );
+      if (inlined !== null) {
+        return inlined;
+      }
+    }
+    // Anything opaque — a factory, a scoped binding, an activation hook, a class the compiler
+    // declined — runs on the runtime path, seeded with this plan's ancestors.
+    return this.#compileEscapeThunk(binding.token, ancestors);
+  }
+}

package/src/{lifecycle.ts → resolution/lifecycle.ts}

@@ -9,35 +9,43 @@ import type { ActivationHandler, Constructor, DeactivationHandler, ResolutionCon
  * @since 0.3.16-canary.0
  */
 export class LifecycleManager {
-  // Container-level activation/deactivation hooks per token
-  private readonly _activationHooks = new Map<Token<unknown> | Constructor, Array<ActivationHandler<unknown>>>();
-  private readonly _deactivationHooks = new Map<Token<unknown> | Constructor, Array<DeactivationHandler<unknown>>>();
-  private _activationVersion = 0;
+  // Container-level activation/deactivation hooks per token — most containers register none, so
+  // both tables stay unallocated until the first hook arrives.
+  #activationHooks: Map<Token<unknown> | Constructor, Array<ActivationHandler<unknown>>> | undefined;
+  #deactivationHooks: Map<Token<unknown> | Constructor, Array<DeactivationHandler<unknown>>> | undefined;
+  #activationVersion = 0;
 
   registerActivation<const Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void {
-    this._activationVersion += 1;
+    this.#activationVersion += 1;
     // ✓ TS6.0: Map.getOrInsert (ES2025)
-    const list = this._activationHooks.getOrInsert(token as Token<unknown> | Constructor, []);
+    const list = (this.#activationHooks ??= new Map()).getOrInsert(token as Token<unknown> | Constructor, []);
     list.push(handler as ActivationHandler<unknown>);
   }
 
   hasActivationHandlers<const Value>(token: Token<Value> | Constructor<Value>): boolean {
-    if (this._activationHooks.size === 0) {
+    if (this.#activationHooks === undefined) {
       return false;
     }
-    const list = this._activationHooks.get(token as Token<unknown> | Constructor);
+    const list = this.#activationHooks.get(token as Token<unknown> | Constructor);
     return list !== undefined && list.length > 0;
   }
 
   get activationVersion(): number {
-    return this._activationVersion;
+    return this.#activationVersion;
+  }
+
+  /** Container-level activation handlers for a token — hot-path accessor, no copies. */
+  activationHandlersFor<const Value>(
+    token: Token<Value> | Constructor<Value>,
+  ): ReadonlyArray<ActivationHandler<unknown>> | undefined {
+    return this.#activationHooks?.get(token as Token<unknown> | Constructor);
   }
 
   registerDeactivation<const Value>(
     token: Token<Value> | Constructor<Value>,
     handler: DeactivationHandler<Value>,
   ): void {
-    const list = this._deactivationHooks.getOrInsert(token as Token<unknown> | Constructor, []);
+    const list = (this.#deactivationHooks ??= new Map()).getOrInsert(token as Token<unknown> | Constructor, []);
     list.push(handler as DeactivationHandler<unknown>);
   }
 
@@ -72,7 +80,7 @@ export class LifecycleManager {
     }
 
     // 3. container-level onActivation
-    const containerHooks = this._activationHooks.get(binding.token as Token<unknown> | Constructor);
+    const containerHooks = this.#activationHooks?.get(binding.token as Token<unknown> | Constructor);
     if (containerHooks !== undefined) {
       for (const hook of containerHooks) {
         const activationResult = hook(resolutionContext, activatedInstance);
@@ -118,7 +126,7 @@ export class LifecycleManager {
 
     // 3. container-level onActivation (must be sync)
     const tokenDisplayName = tokenName(binding.token);
-    const containerHooks = this._activationHooks.get(binding.token as Token<unknown> | Constructor);
+    const containerHooks = this.#activationHooks?.get(binding.token as Token<unknown> | Constructor);
     if (containerHooks !== undefined) {
       for (const hook of containerHooks) {
         const activationResult = hook(resolutionContext, activatedInstance);
@@ -140,7 +148,7 @@ export class LifecycleManager {
     const tokenKey = binding.token as Token<unknown> | Constructor;
 
     // 1. container-level onDeactivation
-    const containerHooks = this._deactivationHooks.get(tokenKey);
+    const containerHooks = this.#deactivationHooks?.get(tokenKey);
     if (containerHooks !== undefined) {
       for (const hook of containerHooks) {
         const hookResult = hook(instance);
@@ -180,7 +188,7 @@ export class LifecycleManager {
     const tokenKey = binding.token as Token<unknown> | Constructor;
 
     // 1. container-level onDeactivation
-    const containerHooks = this._deactivationHooks.get(tokenKey);
+    const containerHooks = this.#deactivationHooks?.get(tokenKey);
     if (containerHooks !== undefined) {
       for (const hook of containerHooks) {
         const hookResult = hook(instance);
@@ -214,4 +222,8 @@ export class LifecycleManager {
       }
     }
   }
+  /** Whether the deferred table behind `#activationHooks` has had to be built. */
+  get isBuilt(): boolean {
+    return this.#activationHooks !== undefined;
+  }
 }