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

package/src/resolution/instantiation-plan.ts

@@ -1,28 +1,21 @@
 /**
- * Compiler for the resolver's Dagger-style instantiation plans: a transient
- * class or resolved-factory binding whose dependency subgraph is pure static
- * (class/constant/cached-singleton deps, no activation hooks or postConstruct)
- * compiles once into a nested-constructor/factory closure, cycle-checked at
- * compile time.
+ * Compiles a transient class or resolved-factory binding into a nested-constructor closure.
  *
- * Compilation is cold-path — it runs once per (binding, cache version). The
- * closures it returns ARE the hot path and touch nothing but their captures.
- * Anything dynamic refuses to compile so the runtime cycle guard stays in
- * charge and error semantics never change.
+ * @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 { ScopeManager } from "#/resolution/scope";
-import { SINGLETON_MISS } from "#/resolution/scope";
 import type { Token } from "#/token";
 import { tokenName } from "#/token";
-import type { BindingScope, Constructor } from "#/types";
+import type { BindingScope, Constructor, ResolutionFrame, ResolveOptions } from "#/types";
 
-// Bail out of pathological graphs — the runtime path handles them correctly.
+// 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;
 
 /**
@@ -41,13 +34,20 @@ export const PLAN_RETRY: unique symbol = Symbol("di:plan-retry");
 export type InstantiationPlanCompileResult = (() => unknown) | null | typeof PLAN_RETRY;
 
 /**
- * A dependency's terminal binding plus the scope cache of the resolver that owns it.
+ * 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;
-  readonly ownerScope: ScopeManager;
 }
 
 /**
@@ -64,10 +64,26 @@ export interface InstantiationPlanHost {
   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;
-  /** Full runtime resolve — used by singleton thunks for the first materialization. */
-  resolveFallback(token: Token<unknown> | Constructor): unknown;
+  /** 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
  */
@@ -80,8 +96,26 @@ export class InstantiationPlanCompiler {
 
   compile(binding: Binding & { kind: "class" | "resolved" }): InstantiationPlanCompileResult {
     return binding.kind === "class"
-      ? this.#compileClassPlan(binding, new Set(), 0)
-      : this.#compileResolvedPlan(binding, new Set(), 0);
+      ? 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
@@ -90,21 +124,20 @@ export class InstantiationPlanCompiler {
     binding: Binding & { kind: "resolved" },
     compileStack: Set<Binding["id"]>,
     depth: number,
+    ancestors: ReadonlyArray<Binding>,
   ): InstantiationPlanCompileResult {
-    if (depth > PLAN_DEPTH_LIMIT || compileStack.has(binding.id)) {
-      return null;
-    }
     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.#compileDescriptorThunk(binding.deps[index]!, compileStack, depth);
-        if (thunk === null || thunk === PLAN_RETRY) {
+        const thunk = this.#compileInjectionThunk(binding.deps[index]!, compileStack, depth, depAncestors);
+        if (thunk === PLAN_RETRY) {
           return thunk;
         }
         depThunks[index] = thunk;
@@ -121,29 +154,41 @@ export class InstantiationPlanCompiler {
     };
   }
 
-  #compileDescriptorThunk(
+  /**
+   * 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,
-  ): InstantiationPlanCompileResult {
-    if (descriptor.multi || descriptor.optional || injectionSlotToResolveOptions(descriptor) !== undefined) {
-      return null;
+    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);
     }
-    const entry = this.#host.lookupDependencyEntry(descriptor.token as Token<unknown> | Constructor);
+    if (options !== undefined) {
+      return this.#compileEscapeThunk(token, ancestors, "single", options);
+    }
+    const entry = this.#host.lookupDependencyEntry(token);
     if (entry === null) {
-      return null;
+      return this.#compileEscapeThunk(token, ancestors);
     }
-    return this.#compileDepThunk(entry, compileStack, depth);
+    return this.#compileDepThunk(entry, compileStack, depth, ancestors);
   }
 
   #compileClassPlan(
     binding: Binding & { kind: "class" },
     compileStack: Set<Binding["id"]>,
     depth: number,
+    ancestors: ReadonlyArray<Binding>,
   ): InstantiationPlanCompileResult {
-    if (depth > PLAN_DEPTH_LIMIT || compileStack.has(binding.id)) {
-      return null;
-    }
     if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding.token)) {
       return null;
     }
@@ -166,19 +211,12 @@ export class InstantiationPlanCompiler {
       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 param = params[index]!;
-        if (param.multi || param.optional || injectionSlotToResolveOptions(param) !== undefined) {
-          return null;
-        }
-        const entry = this.#host.lookupDependencyEntry(param.token);
-        if (entry === null) {
-          return null;
-        }
-        const thunk = this.#compileDepThunk(entry, compileStack, depth);
-        if (thunk === null || thunk === PLAN_RETRY) {
+        const thunk = this.#compileInjectionThunk(params[index]!, compileStack, depth, depAncestors);
+        if (thunk === PLAN_RETRY) {
           return thunk;
         }
         depThunks[index] = thunk;
@@ -211,30 +249,44 @@ export class InstantiationPlanCompiler {
     entry: InstantiationPlanDependencyEntry,
     compileStack: Set<Binding["id"]>,
     depth: number,
-  ): InstantiationPlanCompileResult {
-    const { binding, ownerScope } = entry;
-    if (binding.kind === "constant") {
-      if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding.token)) {
-        return null;
+    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 value = binding.value;
-      return () => value;
     }
     const scope = (binding as Binding & { scope: BindingScope }).scope ?? "transient";
     if (scope === "singleton") {
-      // Cached-singleton read with a full-resolve fallback for the first materialization.
-      const host = this.#host;
-      const bindingId = binding.id;
-      const singletonToken = binding.token;
+      // 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 cachedSingleton = ownerScope.peekSingleton(bindingId);
-        return cachedSingleton === SINGLETON_MISS ? host.resolveFallback(singletonToken) : cachedSingleton;
+        const cached = singletonBinding.instance;
+        return cached === NO_INSTANCE ? escape() : cached;
       };
     }
-    if (scope === "transient" && binding.kind === "class") {
-      return this.#compileClassPlan(binding as Binding & { kind: "class" }, compileStack, depth + 1);
+    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;
+      }
     }
-    // Dynamic/resolved/scoped deps keep the runtime path (and its cycle guard).
-    return null;
+    // 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/resolution/lifecycle.ts

@@ -9,20 +9,21 @@ import type { ActivationHandler, Constructor, DeactivationHandler, ResolutionCon
  * @since 0.3.16-canary.0
  */
 export class LifecycleManager {
-  // Container-level activation/deactivation hooks per token
-  readonly #activationHooks = new Map<Token<unknown> | Constructor, Array<ActivationHandler<unknown>>>();
-  readonly #deactivationHooks = new Map<Token<unknown> | Constructor, Array<DeactivationHandler<unknown>>>();
+  // 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;
     // ✓ 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);
@@ -37,14 +38,14 @@ export class LifecycleManager {
   activationHandlersFor<const Value>(
     token: Token<Value> | Constructor<Value>,
   ): ReadonlyArray<ActivationHandler<unknown>> | undefined {
-    return this.#activationHooks.get(token as Token<unknown> | Constructor);
+    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>);
   }
 
@@ -79,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);
@@ -125,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);
@@ -147,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);
@@ -187,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);
@@ -221,4 +222,8 @@ export class LifecycleManager {
       }
     }
   }
+  /** Whether the deferred table behind `#activationHooks` has had to be built. */
+  get isBuilt(): boolean {
+    return this.#activationHooks !== undefined;
+  }
 }

package/src/resolution/resolution-path.ts

@@ -1,21 +1,11 @@
-/**
- * Cycle-detection bookkeeping shared by every resolution path.
- *
- * The resolution path is a plain string array for cheap push/pop; past
- * RESOLUTION_SET_THRESHOLD entries an O(1) membership Set is attached to the
- * array itself (symbol-keyed) so very deep graphs keep bounded cycle checks.
- */
+/** Cycle-detection bookkeeping carried on the resolution path itself. */
 import { CircularDependencyError } from "#/errors";
 
 const RESOLUTION_SET_KEY: unique symbol = Symbol("di:resolution-set");
 /**
  * Where the cycle check switches from a linear `Array.includes` scan to an attached Set.
  *
- * @remarks Re-measured on Node 26 / M3 Max over an async transient chain (ns/op at depth
- * 16 / 32 / 64 / 128): a threshold of 128 gives 1275 / 3641 / 9645 / 26082, of 32 gives
- * 1202 / 3285 / 7735 / 16837, of 16 gives 1299 / 3694 / 7449 / 15625. Switching at 32 wins
- * the shallow-to-mid depths real graphs actually have while staying close to the best deep
- * numbers; the previous value of 128 was the worst of the three almost everywhere.
+ * @see `ARCHITECTURE.md` — the depth sweep this value comes from.
  *
  * @since 0.5.0-canary.7
  */
@@ -23,11 +13,9 @@ export const RESOLUTION_SET_THRESHOLD = 32;
 type ResolutionPathWithSet = Array<string> & { [RESOLUTION_SET_KEY]?: Set<string> };
 
 /**
- * Shared cycle guard for every transient resolution path: attaches the O(1) membership
- * Set to the path array (lazily past RESOLUTION_SET_THRESHOLD, eagerly when `forceSet`),
- * throws on a repeated token, then marks the token on both structures.
+ * Marks a token as in-flight on this path, throwing if it is already there.
  *
- * Callers unmark with `resolutionPath.pop()` + `set?.delete(name)` on unwind.
+ * @remarks Unmark with `resolutionPath.pop()` plus `set?.delete(name)`, or {@link exitResolutionPath}.
  */
 export function enterResolutionPath(
   resolutionPath: Array<string>,
@@ -62,10 +50,7 @@ export function enterResolutionPath(
 }
 
 /**
- * Unwinds the innermost `enterResolutionPath` entry, keeping the attached membership Set in
- * sync. Callers that already hold the entry's name can pop and delete directly; this exists for
- * unwind paths that only have the path array — notably the async chain's shared settle callback,
- * which serves every level and therefore cannot capture a per-level name.
+ * Unwinds the innermost {@link enterResolutionPath} entry, for callers that hold only the path.
  *
  * @since 0.5.0-canary.7
  */