@codefast/di 0.5.0-canary.8 → 0.5.0

package/src/resolution/binding-scope.ts

@@ -2,25 +2,14 @@ import type { Binding } from "#/binding";
 import type { BindingScope } from "#/types";
 
 /**
- * Runtime scope used for validation and introspection. Alias bindings are treated as transient
- * because they defer scope to the aliased target at resolve time.
+ * The scope a binding resolves under.
+ *
+ * @remarks Every kind declares one — an alias declares `transient`, since it defers scoping to the
+ * binding it points at — so this is a field read, kept as a named function because it is the
+ * vocabulary validation and introspection speak.
  *
  * @since 0.3.16-canary.0
  */
 export function effectiveBindingScope(binding: Binding): BindingScope {
-  switch (binding.kind) {
-    case "alias":
-      return "transient";
-    case "class":
-    case "constant":
-    case "dynamic":
-    case "dynamic-async":
-    case "resolved":
-    case "resolved-async":
-      return binding.scope;
-    default: {
-      const exhaustive: never = binding;
-      return exhaustive;
-    }
-  }
+  return binding.scope;
 }

package/src/resolution/binding-select.ts

@@ -1,4 +1,4 @@
-import type { Binding } from "#/binding";
+import type { Binding, BindingSlot } from "#/binding";
 import { AmbiguousBindingError } from "#/errors";
 import type { BindingTag, ConstraintContext, ResolveOptions } from "#/types";
 
@@ -62,50 +62,29 @@ function filterBindings(
   ctx: ConstraintContext,
   selectionMode: "single" | "all" = "single",
 ): Array<Binding> {
-  if (options === undefined) {
-    const resultWithoutOptions: Array<Binding> = [];
-    if (selectionMode === "all") {
-      for (const binding of bindings) {
-        if (matchesPredicate(binding, ctx)) {
-          resultWithoutOptions.push(binding);
-        }
-      }
-    } else {
-      for (const binding of bindings) {
-        const slot = binding.slot;
-        if (slot.name === undefined && slot.tags.length === 0 && matchesPredicate(binding, ctx)) {
-          resultWithoutOptions.push(binding);
-        }
-      }
-    }
-    return resultWithoutOptions;
-  }
-
+  // `resolveAll` with no slot criterion takes every binding; `resolve` always matches the slot,
+  // where an absent criterion means "the default slot".
+  const requiresSlotMatch = selectionMode === "single" || (options !== undefined && hasSlotCriterion(options));
   const result: Array<Binding> = [];
   for (const binding of bindings) {
-    const slotMatched =
-      selectionMode === "all" ? matchesSlotForResolveAll(binding, options) : matchesSlot(binding, options);
-    if (slotMatched && matchesPredicate(binding, ctx)) {
+    if ((!requiresSlotMatch || matchesSlot(binding.slot, options)) && matchesPredicate(binding, ctx)) {
       result.push(binding);
     }
   }
   return result;
 }
 
-function matchesSlotForResolveAll(binding: Binding, options: ResolveOptions | undefined): boolean {
-  const hasExplicitSlotFilter =
-    options !== undefined &&
-    (options.name !== undefined ||
-      (options.tags !== undefined && options.tags.length > 0) ||
-      options.tag !== undefined);
-  if (!hasExplicitSlotFilter) {
-    return true;
-  }
-  return matchesSlot(binding, options);
+function hasSlotCriterion(options: ResolveOptions): boolean {
+  return options.name !== undefined || options.tag !== undefined || (options.tags?.length ?? 0) > 0;
 }
 
-function matchesSlot(binding: Binding, options: ResolveOptions | undefined): boolean {
-  const slot = binding.slot;
+/**
+ * Whether a binding's slot satisfies a request: names must be equal, and every tag the slot
+ * declares must be among the tags requested (SPEC §6.9).
+ *
+ * @since 0.5.0-canary.9
+ */
+export function matchesSlot(slot: BindingSlot, options: ResolveOptions | undefined): boolean {
   const requestedName = options?.name;
   const requestedTags = options?.tags;
   const singleRequestedTag = options?.tag;

package/src/resolution/diagnostics.ts

@@ -27,8 +27,8 @@ export interface ResolutionDiagnostics {
   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;
+  /** Scoped instances currently cached by this container's scope manager. */
+  readonly scopedInstanceCount: number;
   /** Deferred collaborators this container has had to build. */
   readonly builtSubsystems: ReadonlyArray<string>;
 }

package/src/resolution/environment.ts

@@ -1,4 +1,6 @@
 import type { Container } from "#/container/container";
+import type { BranchDepth, OwnedBranchPath, OwnedBranchStack } from "#/resolution/resolution-path";
+import { UNOWNED_BRANCH } from "#/resolution/resolution-path";
 import type { Token } from "#/token";
 import type {
   BindingIdentifier,
@@ -56,8 +58,10 @@ export interface ResolverCallbacks {
     token: Token<Value> | Constructor<Value>,
     resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
-    callerContext?: DefaultResolutionContext,
+    branchDepth: BranchDepth,
   ): Promise<Value>;
+  /** Not one of the eight `Value`-naming entry points: its caller is, and casts once. */
+  resolveAsyncFromCascade(token: Token<unknown> | Constructor): Promise<unknown>;
   resolveAsync<const Value>(
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
@@ -106,7 +110,6 @@ export class DefaultResolutionContext implements ResolutionContext {
     currentOptions: ResolveOptions | undefined,
   ) {
     this.#resolver = resolver;
-    this.owner = resolver;
     this.#resolutionPath = resolutionPath;
     this.#resolutionStack = resolutionStack;
     this.#currentOptions = currentOptions;
@@ -114,30 +117,6 @@ export class DefaultResolutionContext implements ResolutionContext {
 
   #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);
@@ -151,14 +130,21 @@ export class DefaultResolutionContext implements ResolutionContext {
     resolutionStack: Array<ResolutionFrame>,
     currentOptions: ResolveOptions | undefined,
   ): void {
-    this.#resolver = resolver;
-    this.owner = resolver;
-    this.#resolutionPath = resolutionPath;
-    this.#resolutionStack = resolutionStack;
+    // Compared before storing: a pooled context lives long enough to be in old space, so storing a
+    // pointer costs a write barrier, and a sync resolve hands every depth the same two arrays.
+    if (this.#resolver !== resolver) {
+      this.#resolver = resolver;
+    }
+    if (this.#resolutionPath !== resolutionPath) {
+      this.#resolutionPath = resolutionPath;
+    }
+    if (this.#resolutionStack !== resolutionStack) {
+      this.#resolutionStack = resolutionStack;
+    }
     this.#currentOptions = currentOptions;
-    this.#graph = undefined;
-    this.chainSettle = undefined;
-    this.chainLevels = 0;
+    if (this.#graph !== undefined) {
+      this.#graph = undefined;
+    }
   }
 
   resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
@@ -170,8 +156,8 @@ export class DefaultResolutionContext implements ResolutionContext {
 
   resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
     if (options === undefined) {
-      // 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);
+      // UNOWNED_BRANCH: this frame's array is a sync stack it will pop, so the lane must copy it.
+      return this.#resolver.resolveAsyncFromContext(token, this.#resolutionPath, this.#resolutionStack, UNOWNED_BRANCH);
     }
     return this.#resolver.resolveAsync(token, options, this.#resolutionPath, this.#resolutionStack);
   }
@@ -199,6 +185,166 @@ export class DefaultResolutionContext implements ResolutionContext {
   }
 }
 
+/**
+ * One async level's resolution context, which is also its branch of the resolution path.
+ *
+ * @remarks Separate from {@link DefaultResolutionContext} so the sync lane's pooled context keeps
+ * reading its arrays as plain fields: only an async branch has a prefix to take. See
+ * `ARCHITECTURE.md` — an async level owns its branch of the path.
+ *
+ * @since 0.5.0-canary.9
+ */
+export class AsyncLevelContext implements ResolutionContext {
+  readonly #resolver: ResolverCallbacks;
+  readonly #resolutionPath: OwnedBranchPath;
+  readonly #resolutionStack: OwnedBranchStack;
+  readonly #currentOptions: ResolveOptions | undefined;
+  readonly #branchDepth: BranchDepth;
+
+  /**
+   * @param resolutionPath - this level's own branch; the depth is read off it rather than passed,
+   * so the two cannot disagree about where this level sits
+   */
+  constructor(
+    resolver: ResolverCallbacks,
+    resolutionPath: OwnedBranchPath,
+    resolutionStack: OwnedBranchStack,
+    currentOptions: ResolveOptions | undefined,
+  ) {
+    this.#resolver = resolver;
+    this.#resolutionPath = resolutionPath;
+    this.#resolutionStack = resolutionStack;
+    this.#currentOptions = currentOptions;
+    this.#branchDepth = resolutionPath.length as BranchDepth;
+  }
+
+  #graph: ConstraintContext | undefined;
+  #exactPathCache: Array<string> | undefined;
+  #exactStackCache: Array<ResolutionFrame> | undefined;
+
+  get graph(): ConstraintContext {
+    if (this.#graph === undefined) {
+      this.#graph = new DefaultConstraintContext(this.#exactPath(), this.#exactStack(), this.#currentOptions);
+    }
+    return this.#graph;
+  }
+
+  // The path is append-only and a descendant may already have grown it past this level, so every
+  // caller but the async lane is handed this branch's prefix. It is fixed for the level's lifetime.
+  #exactPath(): Array<string> {
+    return (this.#exactPathCache ??= this.#resolutionPath.slice(0, this.#branchDepth));
+  }
+
+  #exactStack(): Array<ResolutionFrame> {
+    return (this.#exactStackCache ??= this.#resolutionStack.slice(0, this.#branchDepth));
+  }
+
+  resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
+    if (options === undefined) {
+      return this.#resolver.resolveFromContext(token, this.#exactPath(), this.#exactStack());
+    }
+    return this.#resolver.resolve(token, options, this.#exactPath(), this.#exactStack());
+  }
+
+  resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
+    if (options === undefined) {
+      // The hot lane: the resolver reads this branch by depth, so nothing is materialized.
+      return this.#resolver.resolveAsyncFromContext(
+        token,
+        this.#resolutionPath,
+        this.#resolutionStack,
+        this.#branchDepth,
+      );
+    }
+    return this.#resolver.resolveAsync(token, options, this.#exactPath(), this.#exactStack());
+  }
+
+  resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
+    return this.#resolver.resolveOptional(token, options, this.#exactPath(), this.#exactStack());
+  }
+
+  resolveOptionalAsync<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options?: ResolveOptions,
+  ): Promise<Value | undefined> {
+    return this.#resolver.resolveOptionalAsync(token, options, this.#exactPath(), this.#exactStack());
+  }
+
+  resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
+    return this.#resolver.resolveAll(token, options, this.#exactPath(), this.#exactStack());
+  }
+
+  resolveAllAsync<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options?: ResolveOptions,
+  ): Promise<Array<Value>> {
+    return this.#resolver.resolveAllAsync(token, options, this.#exactPath(), this.#exactStack());
+  }
+}
+
+/**
+ * The one context every level of an open synchronous factory cascade shares.
+ *
+ * @remarks It carries no per-level state at all: while the cascade is open, the resolver's arrays
+ * *are* this level's ancestor chain, so nothing has to be allocated per level. See
+ * `ARCHITECTURE.md` — the cascade lane.
+ *
+ * @since 0.5.0-canary.9
+ */
+export class AsyncCascadeContext implements ResolutionContext {
+  readonly #resolver: ResolverCallbacks;
+  readonly #cascadePath: Array<string>;
+  readonly #cascadeStack: Array<ResolutionFrame>;
+
+  constructor(resolver: ResolverCallbacks, cascadePath: Array<string>, cascadeStack: Array<ResolutionFrame>) {
+    this.#resolver = resolver;
+    this.#cascadePath = cascadePath;
+    this.#cascadeStack = cascadeStack;
+  }
+
+  get graph(): ConstraintContext {
+    // Not memoized: this context outlives every level, so a cached graph would describe whichever
+    // level asked first. The cascade arrays are only this level's ancestors while it is open.
+    return new DefaultConstraintContext(this.#cascadePath, this.#cascadeStack, undefined);
+  }
+
+  resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
+    if (options === undefined) {
+      return this.#resolver.resolveFromContext(token, this.#cascadePath, this.#cascadeStack);
+    }
+    return this.#resolver.resolve(token, options, this.#cascadePath, this.#cascadeStack);
+  }
+
+  resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
+    if (options === undefined) {
+      return this.#resolver.resolveAsyncFromCascade(token) as Promise<Value>;
+    }
+    return this.#resolver.resolveAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+  }
+
+  resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
+    return this.#resolver.resolveOptional(token, options, this.#cascadePath, this.#cascadeStack);
+  }
+
+  resolveOptionalAsync<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options?: ResolveOptions,
+  ): Promise<Value | undefined> {
+    return this.#resolver.resolveOptionalAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+  }
+
+  resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
+    return this.#resolver.resolveAll(token, options, this.#cascadePath, this.#cascadeStack);
+  }
+
+  resolveAllAsync<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options?: ResolveOptions,
+  ): Promise<Array<Value>> {
+    return this.#resolver.resolveAllAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+  }
+}
+
 class DefaultConstraintContext implements ConstraintContext {
   readonly resolutionPath: ReadonlyArray<string>;
   readonly resolutionStack: ReadonlyArray<ResolutionFrame>;

package/src/resolution/instantiation-plan.ts

@@ -6,13 +6,13 @@
 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 type { DependencySlot } from "#/resolution/resolve-options";
 import { injectionSlotToResolveOptions } from "#/resolution/resolve-options";
 import type { Token } from "#/token";
 import { tokenName } from "#/token";
-import type { BindingScope, Constructor, ResolutionFrame, ResolveOptions } from "#/types";
+import type { 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.
@@ -160,12 +160,12 @@ export class InstantiationPlanCompiler {
    * @remarks Anything but a plain required single dependency escapes to the runtime path.
    */
   #compileInjectionThunk(
-    descriptor: InjectionDescriptor,
+    descriptor: DependencySlot,
     compileStack: Set<Binding["id"]>,
     depth: number,
     ancestors: ReadonlyArray<Binding>,
   ): DependencyCompileResult {
-    const token = descriptor.token as Token<unknown> | Constructor;
+    const token = descriptor.token;
     const options = injectionSlotToResolveOptions(descriptor);
     if (descriptor.multi) {
       return this.#compileEscapeThunk(token, ancestors, "all", options);
@@ -258,7 +258,7 @@ export class InstantiationPlanCompiler {
         return () => value;
       }
     }
-    const scope = (binding as Binding & { scope: BindingScope }).scope ?? "transient";
+    const scope = binding.scope;
     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.

package/src/resolution/lifecycle.ts

@@ -15,18 +15,22 @@ export class LifecycleManager {
   #deactivationHooks: Map<Token<unknown> | Constructor, Array<DeactivationHandler<unknown>>> | undefined;
   #activationVersion = 0;
 
+  // One-entry cache in front of the map: a resolve loop asks about the same token over and over,
+  // and registration is the only thing that can change the answer.
+  #cachedToken: Token<unknown> | Constructor | undefined;
+  #cachedHooks: Array<ActivationHandler<unknown>> | undefined;
+
   registerActivation<const Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void {
     this.#activationVersion += 1;
+    this.#cachedToken = undefined;
+    this.#cachedHooks = undefined;
     // ✓ TS6.0: Map.getOrInsert (ES2025)
     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 === undefined) {
-      return false;
-    }
-    const list = this.#activationHooks.get(token as Token<unknown> | Constructor);
+    const list = this.activationHandlersFor(token);
     return list !== undefined && list.length > 0;
   }
 
@@ -38,7 +42,18 @@ export class LifecycleManager {
   activationHandlersFor<const Value>(
     token: Token<Value> | Constructor<Value>,
   ): ReadonlyArray<ActivationHandler<unknown>> | undefined {
-    return this.#activationHooks?.get(token as Token<unknown> | Constructor);
+    const hooks = this.#activationHooks;
+    if (hooks === undefined) {
+      return undefined;
+    }
+    const key = token as Token<unknown> | Constructor;
+    if (key === this.#cachedToken) {
+      return this.#cachedHooks;
+    }
+    const list = hooks.get(key);
+    this.#cachedToken = key;
+    this.#cachedHooks = list;
+    return list;
   }
 
   registerDeactivation<const Value>(
@@ -58,18 +73,10 @@ export class LifecycleManager {
     let activatedInstance: Value = instance;
 
     // 1. @postConstruct() — after TC39 construction (constructor + accessor addInitializer callbacks)
-    if (binding.kind === "class") {
-      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
-      if (lifecycle?.postConstruct && lifecycle.postConstruct.length > 0) {
-        for (const methodName of lifecycle.postConstruct) {
-          const method = (activatedInstance as Record<string, unknown>)[methodName];
-          if (typeof method === "function") {
-            const hookResult = (method as () => unknown).call(activatedInstance);
-            if (hookResult instanceof Promise) {
-              await hookResult;
-            }
-          }
-        }
+    for (const methodName of lifecycleMethods(binding, metadataReader, "postConstruct")) {
+      const hookResult = callHook(activatedInstance, methodName);
+      if (hookResult instanceof Promise) {
+        await hookResult;
       }
     }
 
@@ -100,18 +107,9 @@ export class LifecycleManager {
     let activatedInstance: Value = instance;
 
     // 1. @postConstruct() — must be sync (instance fully constructed per TC39 order)
-    if (binding.kind === "class") {
-      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
-      if (lifecycle?.postConstruct && lifecycle.postConstruct.length > 0) {
-        for (const methodName of lifecycle.postConstruct) {
-          const method = (activatedInstance as Record<string, unknown>)[methodName];
-          if (typeof method === "function") {
-            const hookResult = (method as () => unknown).call(activatedInstance);
-            if (hookResult instanceof Promise) {
-              throw new AsyncActivationError(tokenName(binding.token), "postConstruct", methodName);
-            }
-          }
-        }
+    for (const methodName of lifecycleMethods(binding, metadataReader, "postConstruct")) {
+      if (callHook(activatedInstance, methodName) instanceof Promise) {
+        throw new AsyncActivationError(tokenName(binding.token), "postConstruct", methodName);
       }
     }
 
@@ -167,18 +165,10 @@ export class LifecycleManager {
     }
 
     // 3. @preDestroy() — all methods in declaration order
-    if (binding.kind === "class") {
-      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
-      if (lifecycle?.preDestroy && lifecycle.preDestroy.length > 0) {
-        for (const methodName of lifecycle.preDestroy) {
-          const method = (instance as Record<string, unknown>)[methodName];
-          if (typeof method === "function") {
-            const hookResult = (method as () => unknown).call(instance);
-            if (hookResult instanceof Promise) {
-              await hookResult;
-            }
-          }
-        }
+    for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
+      const hookResult = callHook(instance, methodName);
+      if (hookResult instanceof Promise) {
+        await hookResult;
       }
     }
   }
@@ -207,23 +197,35 @@ export class LifecycleManager {
     }
 
     // 3. @preDestroy()
-    if (binding.kind === "class") {
-      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
-      if (lifecycle?.preDestroy && lifecycle.preDestroy.length > 0) {
-        for (const methodName of lifecycle.preDestroy) {
-          const method = (instance as Record<string, unknown>)[methodName];
-          if (typeof method === "function") {
-            const hookResult = (method as () => unknown).call(instance);
-            if (hookResult instanceof Promise) {
-              throw new AsyncDeactivationError(tokenDisplayName);
-            }
-          }
-        }
+    for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
+      if (callHook(instance, methodName) instanceof Promise) {
+        throw new AsyncDeactivationError(tokenDisplayName);
       }
     }
   }
+
   /** Whether the deferred table behind `#activationHooks` has had to be built. */
   get isBuilt(): boolean {
     return this.#activationHooks !== undefined;
   }
 }
+
+const NO_METHODS: ReadonlyArray<string> = [];
+
+/** The `@postConstruct` / `@preDestroy` methods a binding declares — only a class can declare any. */
+function lifecycleMethods<const Value>(
+  binding: Binding<Value>,
+  metadataReader: MetadataReader,
+  phase: "postConstruct" | "preDestroy",
+): ReadonlyArray<string> {
+  if (binding.kind !== "class") {
+    return NO_METHODS;
+  }
+  return metadataReader.getLifecycleMetadata(binding.target)?.[phase] ?? NO_METHODS;
+}
+
+/** Invokes a hook by name, tolerating a name whose member is not (or no longer) a method. */
+function callHook(instance: unknown, methodName: string): unknown {
+  const method = (instance as Record<string, unknown>)[methodName];
+  return typeof method === "function" ? (method as () => unknown).call(instance) : undefined;
+}