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

package/src/registry.ts

@@ -7,79 +7,107 @@ import type { BindingIdentifier, Constructor, DependencyKey } from "#/types";
  * @since 0.3.16-canary.0
  */
 export class BindingRegistry {
+  // Monotonic mutation counter — lets resolvers version-stamp lookup caches across a container chain.
+  #version = 0;
   // Map from token key -> array of bindings (order matters for last-wins)
-  private readonly _bindings = new Map<DependencyKey, Array<Binding>>();
+  readonly #bindings = new Map<DependencyKey, Array<Binding>>();
   // Fast lookup by binding ID
-  private readonly _byId = new Map<BindingIdentifier, Binding>();
-  // Fast lookup for slot { name, tags: [] }
-  private readonly _simpleNamed = new Map<DependencyKey, Map<string, Binding>>();
+  readonly #byId = new Map<BindingIdentifier, Binding>();
+  // Fast lookup for slot { name, tags: [] } — unallocated until a named binding is registered.
+  #simpleNamed: Map<DependencyKey, Map<string, Binding>> | undefined;
   // Fast path for one default slot binding with no predicate
-  private readonly _fastDefault = new Map<DependencyKey, Binding>();
-  // Fast lookup for slot { name: undefined, tags: [[key, value]] } with no predicate
-  private readonly _simpleTagged = new Map<DependencyKey, Map<string, Map<unknown, Binding>>>();
+  readonly #fastDefault = new Map<DependencyKey, Binding>();
+  // Fast lookup for slot { name: undefined, tags: [[key, value]] } with no predicate — likewise
+  // unallocated until a tagged binding is registered.
+  #simpleTagged: Map<DependencyKey, Map<string, Map<unknown, Binding>>> | undefined;
 
-  /** Add or replace binding using slot-aware last-wins. */
-  add(binding: Binding): void {
+  /** Monotonic version — increments on every mutation. */
+  get version(): number {
+    return this.#version;
+  }
+
+  /**
+   * Registers a mutation the indexes don't care about (a fluent chain refining scope or an
+   * activation hook in place), so version-stamped resolver caches still invalidate.
+   */
+  touch(): void {
+    this.#version += 1;
+  }
+
+  /**
+   * Add or replace binding using slot-aware last-wins. Returns the displaced binding, if any.
+   *
+   * @remarks The binding is stored by reference — it must come from `createBinding`, which is
+   * what guarantees the single hidden class the resolver's hot reads depend on.
+   */
+  add(binding: Binding): Binding | undefined {
+    this.#version += 1;
     const key = binding.token as DependencyKey;
     // ✓ TS6.0: Map.getOrInsert (ES2025) replaces the manual get+check+set upsert
-    const bindingsForToken = this._bindings.getOrInsert(key, []);
+    const bindingsForToken = this.#bindings.getOrInsert(key, []);
 
     // Only apply last-wins for slot-based bindings (not predicate-only)
-    if (!this._isPurePredicateBinding(binding)) {
+    let displacedBinding: Binding | undefined;
+    if (!this.#isPurePredicateBinding(binding)) {
       const existingIndex = bindingsForToken.findIndex(
-        (candidate) => !this._isPurePredicateBinding(candidate) && bindingSlotEquals(candidate.slot, binding.slot),
+        (candidate) => !this.#isPurePredicateBinding(candidate) && bindingSlotEquals(candidate.slot, binding.slot),
       );
       if (existingIndex !== -1) {
-        const replacedBinding = bindingsForToken[existingIndex]!;
-        this._byId.delete(replacedBinding.id);
+        displacedBinding = bindingsForToken[existingIndex]!;
+        this.#byId.delete(displacedBinding.id);
         bindingsForToken.splice(existingIndex, 1);
+        this.#deindexSimpleNamedBinding(key, displacedBinding);
+        this.#deindexSimpleTaggedBinding(key, displacedBinding);
       }
     }
 
     bindingsForToken.push(binding);
-    this._byId.set(binding.id, binding);
-    this._indexSimpleNamedBinding(key, binding);
-    this._indexSimpleTaggedBinding(key, binding);
-    this._refreshFastDefaultForToken(key);
+    this.#byId.set(binding.id, binding);
+    this.#indexSimpleNamedBinding(key, binding);
+    this.#indexSimpleTaggedBinding(key, binding);
+    this.#refreshFastDefaultForToken(key);
+    return displacedBinding;
   }
 
   /** Remove all bindings for a token. Returns removed bindings. */
   removeByToken(token: Token<unknown> | Constructor): Array<Binding> {
+    this.#version += 1;
     const key = token as DependencyKey;
-    const bindingsForToken = this._bindings.get(key) ?? [];
-    this._bindings.delete(key);
-    this._simpleNamed.delete(key);
-    this._simpleTagged.delete(key);
-    this._fastDefault.delete(key);
+    const bindingsForToken = this.#bindings.get(key) ?? [];
+    this.#bindings.delete(key);
+    this.#simpleNamed?.delete(key);
+    this.#simpleTagged?.delete(key);
+    this.#fastDefault.delete(key);
     for (const binding of bindingsForToken) {
-      this._byId.delete(binding.id);
+      this.#byId.delete(binding.id);
     }
     return bindingsForToken;
   }
 
   /** Remove a specific binding by ID. Returns the removed binding or undefined. */
   removeById(id: BindingIdentifier): Binding | undefined {
-    const binding = this._byId.get(id);
+    const binding = this.#byId.get(id);
     if (binding === undefined) {
       return undefined;
     }
-    this._byId.delete(id);
+    this.#version += 1;
+    this.#byId.delete(id);
     const key = binding.token as DependencyKey;
-    const bindingsForToken = this._bindings.get(key);
+    const bindingsForToken = this.#bindings.get(key);
     if (bindingsForToken !== undefined) {
       const bindingIndex = bindingsForToken.findIndex((candidate) => candidate.id === id);
       if (bindingIndex !== -1) {
         bindingsForToken.splice(bindingIndex, 1);
       }
-      this._deindexSimpleNamedBinding(key, binding);
-      this._deindexSimpleTaggedBinding(key, binding);
+      this.#deindexSimpleNamedBinding(key, binding);
+      this.#deindexSimpleTaggedBinding(key, binding);
       if (bindingsForToken.length === 0) {
-        this._bindings.delete(key);
-        this._simpleNamed.delete(key);
-        this._simpleTagged.delete(key);
-        this._fastDefault.delete(key);
+        this.#bindings.delete(key);
+        this.#simpleNamed?.delete(key);
+        this.#simpleTagged?.delete(key);
+        this.#fastDefault.delete(key);
       } else {
-        this._refreshFastDefaultForToken(key);
+        this.#refreshFastDefaultForToken(key);
       }
     }
     return binding;
@@ -87,25 +115,25 @@ export class BindingRegistry {
 
   /** Get all bindings for a token. */
   getAll(token: Token<unknown> | Constructor): ReadonlyArray<Binding> {
-    return this._bindings.get(token as DependencyKey) ?? [];
+    return this.#bindings.get(token as DependencyKey) ?? [];
   }
 
   /** Get binding by ID. */
   getById(id: BindingIdentifier): Binding | undefined {
-    return this._byId.get(id);
+    return this.#byId.get(id);
   }
 
   /** Check if any binding exists for token. */
   has(token: Token<unknown> | Constructor): boolean {
     const key = token as DependencyKey;
-    const list = this._bindings.get(key);
+    const list = this.#bindings.get(key);
     return list !== undefined && list.length > 0;
   }
 
   /** All bindings in the registry. */
   allBindings(): ReadonlyArray<Binding> {
     const allBindings: Array<Binding> = [];
-    for (const bindingsForToken of this._bindings.values()) {
+    for (const bindingsForToken of this.#bindings.values()) {
       allBindings.push(...bindingsForToken);
     }
     return allBindings;
@@ -113,54 +141,55 @@ export class BindingRegistry {
 
   /** Remove all bindings. Returns all removed. */
   clear(): ReadonlyArray<Binding> {
+    this.#version += 1;
     const all = this.allBindings();
-    this._bindings.clear();
-    this._byId.clear();
-    this._simpleNamed.clear();
-    this._simpleTagged.clear();
-    this._fastDefault.clear();
+    this.#bindings.clear();
+    this.#byId.clear();
+    this.#simpleNamed?.clear();
+    this.#simpleTagged?.clear();
+    this.#fastDefault.clear();
     return all;
   }
 
   getSimpleNamed(token: Token<unknown> | Constructor, name: string): Binding | undefined {
-    return this._simpleNamed.get(token as DependencyKey)?.get(name);
+    return this.#simpleNamed?.get(token as DependencyKey)?.get(name);
   }
 
   getSimpleTagged(token: Token<unknown> | Constructor, tagKey: string, tagValue: unknown): Binding | undefined {
-    return this._simpleTagged
-      .get(token as DependencyKey)
+    return this.#simpleTagged
+      ?.get(token as DependencyKey)
       ?.get(tagKey)
       ?.get(tagValue);
   }
 
   getFastDefault(token: Token<unknown> | Constructor): Binding | undefined {
-    return this._fastDefault.get(token as DependencyKey);
+    return this.#fastDefault.get(token as DependencyKey);
   }
 
   /** Summarize available slot strings for a token (for error messages). */
   availableSlotStrings(token: Token<unknown> | Constructor): Array<string> {
-    const bindingsForToken = this._bindings.get(token as DependencyKey) ?? [];
+    const bindingsForToken = this.#bindings.get(token as DependencyKey) ?? [];
     return bindingsForToken.map((binding) => bindingSlotToString(binding.slot));
   }
 
-  private _indexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
+  #indexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
     const slot = binding.slot;
     if (slot.name !== undefined || slot.tags.length !== 1 || binding.predicate !== undefined) {
       return;
     }
     const [tagKey, tagValue] = slot.tags[0]!;
-    const byTagKey = this._simpleTagged.getOrInsert(tokenKey, new Map<string, Map<unknown, Binding>>());
+    const byTagKey = (this.#simpleTagged ??= new Map()).getOrInsert(tokenKey, new Map<string, Map<unknown, Binding>>());
     const byTagValue = byTagKey.getOrInsert(tagKey, new Map<unknown, Binding>());
     byTagValue.set(tagValue, binding);
   }
 
-  private _deindexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
+  #deindexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
     const slot = binding.slot;
     if (slot.name !== undefined || slot.tags.length !== 1 || binding.predicate !== undefined) {
       return;
     }
     const [tagKey, tagValue] = slot.tags[0]!;
-    const byTagKey = this._simpleTagged.get(tokenKey);
+    const byTagKey = this.#simpleTagged?.get(tokenKey);
     if (byTagKey === undefined) {
       return;
     }
@@ -174,13 +203,13 @@ export class BindingRegistry {
       if (byTagValue.size === 0) {
         byTagKey.delete(tagKey);
         if (byTagKey.size === 0) {
-          this._simpleTagged.delete(tokenKey);
+          this.#simpleTagged!.delete(tokenKey);
         }
       }
     }
   }
 
-  private _isPurePredicateBinding(binding: Binding): boolean {
+  #isPurePredicateBinding(binding: Binding): boolean {
     const slot = binding.slot;
     const hasPredicate = binding.predicate !== undefined;
     const hasConstraint = slot.name !== undefined || slot.tags.length > 0;
@@ -188,21 +217,21 @@ export class BindingRegistry {
     return hasPredicate && !hasConstraint;
   }
 
-  private _indexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
+  #indexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
     const slot = binding.slot;
     if (slot.name === undefined || slot.tags.length > 0) {
       return;
     }
-    const bindingsByName = this._simpleNamed.getOrInsert(tokenKey, new Map<string, Binding>());
+    const bindingsByName = (this.#simpleNamed ??= new Map()).getOrInsert(tokenKey, new Map<string, Binding>());
     bindingsByName.set(slot.name, binding);
   }
 
-  private _deindexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
+  #deindexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
     const slot = binding.slot;
     if (slot.name === undefined || slot.tags.length > 0) {
       return;
     }
-    const bindingsByName = this._simpleNamed.get(tokenKey);
+    const bindingsByName = this.#simpleNamed?.get(tokenKey);
     if (bindingsByName === undefined) {
       return;
     }
@@ -210,23 +239,27 @@ export class BindingRegistry {
     if (currentBinding?.id === binding.id) {
       bindingsByName.delete(slot.name);
       if (bindingsByName.size === 0) {
-        this._simpleNamed.delete(tokenKey);
+        this.#simpleNamed!.delete(tokenKey);
       }
     }
   }
 
-  private _refreshFastDefaultForToken(tokenKey: DependencyKey): void {
-    const bindingsForToken = this._bindings.get(tokenKey);
+  #refreshFastDefaultForToken(tokenKey: DependencyKey): void {
+    const bindingsForToken = this.#bindings.get(tokenKey);
     if (bindingsForToken === undefined || bindingsForToken.length !== 1) {
-      this._fastDefault.delete(tokenKey);
+      this.#fastDefault.delete(tokenKey);
       return;
     }
     const onlyBinding = bindingsForToken[0]!;
     const isDefaultSlot = onlyBinding.slot.name === undefined && onlyBinding.slot.tags.length === 0;
     if (!isDefaultSlot || onlyBinding.predicate !== undefined) {
-      this._fastDefault.delete(tokenKey);
+      this.#fastDefault.delete(tokenKey);
       return;
     }
-    this._fastDefault.set(tokenKey, onlyBinding);
+    this.#fastDefault.set(tokenKey, onlyBinding);
+  }
+  /** Whether the deferred table behind `#simpleNamed` has had to be built. */
+  get isBuilt(): boolean {
+    return this.#simpleNamed !== undefined;
   }
 }

package/src/resolution/activation-need.ts

@@ -0,0 +1,81 @@
+/**
+ * Per binding: does resolving it have to go through the activation pipeline?
+ *
+ * @remarks Versioned on the lifecycle manager, since `onActivation` can be registered at any time.
+ */
+import type { Binding } from "#/binding";
+import type { ClassIntrospector } from "#/resolution/class-introspector";
+import type { LifecycleManager } from "#/resolution/lifecycle";
+import type { BindingIdentifier } from "#/types";
+
+/**
+ * @since 0.5.0-canary.8
+ */
+export class ActivationNeedCache {
+  readonly #needByBindingId = new Map<BindingIdentifier, boolean>();
+  #version = -1;
+  readonly #lifecycle: LifecycleManager;
+  readonly #classes: ClassIntrospector;
+
+  constructor(lifecycle: LifecycleManager, classes: ClassIntrospector) {
+    this.#lifecycle = lifecycle;
+    this.#classes = classes;
+  }
+
+  needsActivation<const Value>(binding: Binding<Value>): boolean {
+    const lifecycleVersion = this.#lifecycle.activationVersion;
+    // No hooks registered anywhere and none on the binding: only classes can still surprise us,
+    // via a @postConstruct we have not looked for yet.
+    if (
+      lifecycleVersion === 0 &&
+      binding.kind !== "class" &&
+      binding.kind !== "alias" &&
+      binding.onActivation === undefined
+    ) {
+      return false;
+    }
+    if (this.#version !== lifecycleVersion) {
+      this.#needByBindingId.clear();
+      this.#version = lifecycleVersion;
+    }
+    const cached = this.#needByBindingId.get(binding.id);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const needsActivation =
+      binding.kind === "class" ? this.#classNeedsActivation(binding) : this.#nonClassNeedsActivation(binding);
+    this.#needByBindingId.set(binding.id, needsActivation);
+    return needsActivation;
+  }
+
+  /**
+   * Settles a class binding's answer once its lifecycle metadata has actually been read, which
+   * only happens on the first instantiation.
+   *
+   * @returns the answer to use for this resolve — possibly now `false` where it was a
+   * conservative `true`.
+   */
+  refreshAfterFirstInstantiation<Value>(binding: Binding<Value>, needsActivation: boolean): boolean {
+    if (binding.kind !== "class" || this.#classes.knownPostConstruct(binding.target) !== undefined) {
+      return needsActivation;
+    }
+    this.#classes.discoverPostConstruct(binding.target);
+    this.#needByBindingId.delete(binding.id);
+    return this.needsActivation(binding);
+  }
+
+  #classNeedsActivation<const Value>(binding: Binding<Value> & { kind: "class" }): boolean {
+    if (this.#lifecycle.hasActivationHandlers(binding.token) || binding.onActivation !== undefined) {
+      return true;
+    }
+    // Unknown lifecycle metadata: activate once so the first instantiation can settle it.
+    return this.#classes.knownPostConstruct(binding.target) !== false;
+  }
+
+  #nonClassNeedsActivation<const Value>(binding: Binding<Value>): boolean {
+    if (binding.kind !== "alias" && binding.onActivation !== undefined) {
+      return true;
+    }
+    return this.#lifecycle.hasActivationHandlers(binding.token);
+  }
+}

package/src/resolution/binding-lookup-cache.ts

@@ -0,0 +1,132 @@
+/**
+ * Options-less token → terminal binding, memoized per container chain.
+ *
+ * @see `ARCHITECTURE.md` — why these caches form their own parent chain.
+ */
+import type { Binding } from "#/binding";
+import type { BindingRegistry } from "#/registry";
+import type { Token } from "#/token";
+import type { Constructor } from "#/types";
+
+/**
+ * A token's terminal binding with alias hops already folded, plus the container that owns it.
+ *
+ * @typeParam Owner - the resolver type, kept generic so this module stays free of resolver internals
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface DefaultLookupEntry<Owner> {
+  readonly binding: Binding;
+  readonly owner: Owner;
+}
+
+/**
+ * Alias folding gives up past this many hops and defers to the full resolve loop, whose
+ * Set-based traversal detects genuine cycles exactly rather than by an arbitrary cap.
+ *
+ * @since 0.5.0-canary.8
+ */
+export const ALIAS_HOP_LIMIT = 32;
+
+/**
+ * @since 0.5.0-canary.8
+ */
+export class BindingLookupCache<Owner> {
+  readonly #byToken = new Map<Token<unknown> | Constructor, DefaultLookupEntry<Owner> | null>();
+  #version = -1;
+  readonly #byTokenAndName = new Map<Token<unknown> | Constructor, Map<string, DefaultLookupEntry<Owner> | null>>();
+  #namedVersion = -1;
+
+  readonly #registry: BindingRegistry;
+  readonly #owner: Owner;
+  readonly #parent: BindingLookupCache<Owner> | undefined;
+
+  constructor(registry: BindingRegistry, owner: Owner, parent: BindingLookupCache<Owner> | undefined) {
+    this.#registry = registry;
+    this.#owner = owner;
+    this.#parent = parent;
+  }
+
+  /** Summed registry versions of this cache's whole chain — the memo stamp. */
+  chainVersion(): number {
+    let version = this.#registry.version;
+    for (let cache = this.#parent; cache !== undefined; cache = cache.#parent) {
+      version += cache.#registry.version;
+    }
+    return version;
+  }
+
+  /** `null` when the token's shape needs the full selection path. */
+  defaultEntry(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
+    const version = this.chainVersion();
+    if (version !== this.#version) {
+      this.#byToken.clear();
+      this.#version = version;
+    }
+    let entry = this.#byToken.get(token);
+    if (entry === undefined) {
+      entry = this.#foldAliases(token);
+      this.#byToken.set(token, entry);
+    }
+    return entry;
+  }
+
+  /** `null` when the name's shape needs the full selection path. */
+  namedEntry(token: Token<unknown> | Constructor, name: string): DefaultLookupEntry<Owner> | null {
+    const version = this.chainVersion();
+    if (version !== this.#namedVersion) {
+      this.#byTokenAndName.clear();
+      this.#namedVersion = version;
+    }
+    // ✓ TS6.0: Map.getOrInsert (ES2025)
+    const byName = this.#byTokenAndName.getOrInsert(token, new Map<string, DefaultLookupEntry<Owner> | null>());
+    let entry = byName.get(name);
+    if (entry === undefined) {
+      entry = this.#findNamedInChain(token, name);
+      byName.set(name, entry);
+    }
+    return entry;
+  }
+
+  #foldAliases(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
+    let current = token;
+    for (let hop = 0; hop < ALIAS_HOP_LIMIT; hop += 1) {
+      const entry = this.#findDefaultInChain(current);
+      if (entry === null) {
+        return null;
+      }
+      if (entry.binding.kind !== "alias") {
+        return entry;
+      }
+      current = entry.binding.target;
+    }
+    return null;
+  }
+
+  #findDefaultInChain(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
+    const fast = this.#registry.getFastDefault(token);
+    if (fast !== undefined) {
+      return { binding: fast, owner: this.#owner };
+    }
+    // A level with non-fast bindings (multi-slot / predicate) needs full selection — bail.
+    if (this.#registry.has(token)) {
+      return null;
+    }
+    return this.#parent === undefined ? null : this.#parent.#findDefaultInChain(token);
+  }
+
+  #findNamedInChain(token: Token<unknown> | Constructor, name: string): DefaultLookupEntry<Owner> | null {
+    const named = this.#registry.getSimpleNamed(token, name);
+    if (named !== undefined) {
+      // Predicates need a live context; aliases carry options through the full path.
+      if (named.predicate !== undefined || named.kind === "alias") {
+        return null;
+      }
+      return { binding: named, owner: this.#owner };
+    }
+    if (this.#registry.has(token)) {
+      return null;
+    }
+    return this.#parent === undefined ? null : this.#parent.#findNamedInChain(token, name);
+  }
+}

package/src/{binding-select.ts → resolution/binding-select.ts}

@@ -21,9 +21,22 @@ export function selectBinding(
   if (candidates.length === 1) {
     return candidates[0];
   }
-  // Multiple candidates — check if any is unambiguous (slot-based selection)
-  // Slot-based bindings already have last-wins applied in registry, so
-  // multiple candidates here means ambiguous predicate-only bindings
+  // Most specific wins: a single matching predicate-carrying candidate beats
+  // predicate-less ones (a predicate is a deliberate specialization of the
+  // default). Two matching predicates are genuinely ambiguous.
+  let predicatedCandidate: Binding | undefined;
+  for (const candidate of candidates) {
+    if (candidate.predicate !== undefined) {
+      if (predicatedCandidate !== undefined) {
+        predicatedCandidate = undefined;
+        break;
+      }
+      predicatedCandidate = candidate;
+    }
+  }
+  if (predicatedCandidate !== undefined) {
+    return predicatedCandidate;
+  }
   throw new AmbiguousBindingError(
     tokenDisplayName,
     candidates.map((c) => c.id),
@@ -122,10 +135,7 @@ function matchesSlot(binding: Binding, options: ResolveOptions | undefined): boo
       }
     }
   } else if (hasRequestedTags) {
-    // Binding has no tags but options requires tags — no match for tagged slots
-    // But: default slot (no tags, no name) can match when options has tags if there are no tag-slotted bindings
-    // Actually per spec: resolveAll with tags only returns bindings that have those tags
-    // and resolve with tags requires exact match
+    // Requested tags require a tagged slot: an untagged binding never matches (SPEC §6.9).
     return false;
   }
 

package/src/resolution/class-introspector.ts

@@ -0,0 +1,74 @@
+/**
+ * Per-class decorator metadata, cached by constructor.
+ *
+ * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
+ */
+
+import type { ConstructorInvocation } from "#/constructor-type";
+import type { Container } from "#/container/container";
+import type { ConstructorMetadata, MetadataReader } from "#/metadata/metadata-types";
+import { runWithContainer } from "#/resolution/environment";
+import type { Constructor } from "#/types";
+
+/**
+ * @since 0.5.0-canary.8
+ */
+export class ClassIntrospector {
+  // Unallocated until the container resolves its first class binding — a container bound entirely
+  // to constants, factories or aliases never introspects one.
+  #constructorMetadata: WeakMap<Constructor, ConstructorMetadata | null> | undefined;
+  #hasPostConstruct: WeakMap<Constructor, boolean> | undefined;
+  #needsActiveContainer: WeakMap<Constructor, boolean> | undefined;
+  readonly #reader: MetadataReader;
+  readonly #container: Container;
+
+  constructor(reader: MetadataReader, container: Container) {
+    this.#reader = reader;
+    this.#container = container;
+  }
+
+  constructorMetadata(target: Constructor): ConstructorMetadata | undefined {
+    const cached = this.#constructorMetadata?.get(target);
+    if (cached !== undefined) {
+      return cached === null ? undefined : cached;
+    }
+    const metadata = this.#reader.getConstructorMetadata(target);
+    (this.#constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
+    return metadata;
+  }
+
+  /**
+   * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
+   *
+   * @remarks Callers treat unknown as "assume it does", so the first activation settles it.
+   */
+  knownPostConstruct(target: Constructor): boolean | undefined {
+    return this.#hasPostConstruct?.get(target);
+  }
+
+  discoverPostConstruct(target: Constructor): void {
+    const lifecycle = this.#reader.getLifecycleMetadata(target);
+    (this.#hasPostConstruct ??= new WeakMap()).set(
+      target,
+      lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0,
+    );
+  }
+
+  /** True when the class has accessor injection, which reads the container during construction. */
+  needsActiveContainer(target: Constructor): boolean {
+    let needsActiveContainer = this.#needsActiveContainer?.get(target);
+    if (needsActiveContainer === undefined) {
+      needsActiveContainer = (this.#reader.getAccessorMetadata?.(target)?.length ?? 0) > 0;
+      (this.#needsActiveContainer ??= new WeakMap()).set(target, needsActiveContainer);
+    }
+    return needsActiveContainer;
+  }
+
+  instantiate(target: Constructor, deps: Array<unknown>): unknown {
+    const invokable = target as ConstructorInvocation;
+    if (!this.needsActiveContainer(target)) {
+      return new invokable(...deps);
+    }
+    return runWithContainer(this.#container, () => new invokable(...deps));
+  }
+}