@fluojs/di 2.0.0 → 3.0.0

package/dist/container.js

@@ -1,6 +1,7 @@
 import { formatTokenName, InvariantError } from '@fluojs/core';
 import { getClassDiMetadata } from '@fluojs/core/internal';
 import { CircularDependencyError, ContainerResolutionError, DuplicateProviderError, RequestScopeResolutionError, ScopeMismatchError } from './errors.js';
+import { registerMultiContributionResolver } from './multi-contribution-registry.js';
 import { normalizeProvider } from './provider-normalization.js';
 import { isForwardRef, isOptionalToken, Scope } from './types.js';
 
@@ -98,17 +99,89 @@ class ReadonlyMultiRegistrationMapView {
 function isPromiseLike(value) {
   return (typeof value === 'object' || typeof value === 'function') && value !== null && typeof value.then === 'function';
 }
+const pendingResolutionContexts = new WeakMap();
+const pendingResolutionOwners = new WeakMap();
+function trackPendingResolution(promise, activeTokens) {
+  const context = pendingResolutionContexts.get(activeTokens) ?? {
+    dependencies: new Map(),
+    pendingPromises: 0
+  };
+  context.pendingPromises += 1;
+  pendingResolutionContexts.set(activeTokens, context);
+  pendingResolutionOwners.set(promise, activeTokens);
+}
+function untrackPendingResolution(promise, activeTokens) {
+  const context = pendingResolutionContexts.get(activeTokens);
+  pendingResolutionOwners.delete(promise);
+  if (!context) {
+    return;
+  }
+  context.pendingPromises -= 1;
+  if (context.pendingPromises === 0 && context.dependencies.size === 0) {
+    pendingResolutionContexts.delete(activeTokens);
+  }
+}
+function findPendingResolutionPath(start, target, visited) {
+  if (start === target) {
+    return [start];
+  }
+  if (visited.has(start)) {
+    return undefined;
+  }
+  visited.add(start);
+  for (const dependency of pendingResolutionContexts.get(start)?.dependencies.keys() ?? []) {
+    const path = findPendingResolutionPath(dependency, target, visited);
+    if (path) {
+      return [start, ...path];
+    }
+  }
+  return undefined;
+}
+function linkPendingResolution(promise, activeTokens, token) {
+  const owner = pendingResolutionOwners.get(promise);
+  if (!owner || activeTokens.size === 0) {
+    return undefined;
+  }
+  const cyclePath = findPendingResolutionPath(owner, activeTokens, new Set());
+  if (cyclePath) {
+    throw new CircularDependencyError([...activeTokens, token, ...cyclePath.flatMap(context => [...context])]);
+  }
+  const context = pendingResolutionContexts.get(activeTokens) ?? {
+    dependencies: new Map(),
+    pendingPromises: 0
+  };
+  context.dependencies.set(owner, (context.dependencies.get(owner) ?? 0) + 1);
+  pendingResolutionContexts.set(activeTokens, context);
+  return () => {
+    const dependencyCount = context.dependencies.get(owner);
+    if (dependencyCount === undefined) {
+      return;
+    }
+    if (dependencyCount === 1) {
+      context.dependencies.delete(owner);
+    } else {
+      context.dependencies.set(owner, dependencyCount - 1);
+    }
+    if (context.pendingPromises === 0 && context.dependencies.size === 0) {
+      pendingResolutionContexts.delete(activeTokens);
+    }
+  };
+}
 
 /**
  * Scope-aware dependency injection container for Fluo providers.
  */
+// allow: SIZE_OK — Container is the package's existing DI lifecycle state machine.
 export class Container {
+  static #childScopeConstruction;
   registrations = new Map();
   multiRegistrations = new Map();
   multiOverriddenTokens = new Set();
   requestCache;
   multiRequestCache;
   multiSingletonCache = new Map();
+  materializedCachePromises = [];
+  pendingDisposables = [];
   staleDisposalTasks = new Set();
   singletonCache;
   forwardRefTokenCache = new WeakMap();
@@ -122,10 +195,38 @@ export class Container {
   disposed = false;
   trackedByParent = false;
   graphRevision = 0;
-  constructor(parent, requestScopeEnabled = false, singletonCache) {
-    this.parent = parent;
-    this.requestScopeEnabled = requestScopeEnabled;
-    this.singletonCache = singletonCache ?? new Map();
+  parent;
+  requestScopeEnabled;
+
+  /**
+   * Creates a root container that owns its own singleton cache.
+   *
+   * Child request scopes are package-owned and must be created with
+   * {@link Container.createRequestScope}; caller-supplied parent, request-scope,
+   * or singleton-cache wiring is rejected.
+   *
+   * @throws {ContainerResolutionError} When any constructor argument is supplied.
+   */
+  constructor(...construction) {
+    if (construction.length > 0) {
+      throw new ContainerResolutionError('Container child-scope construction is package-owned and cannot be invoked directly.', {
+        hint: 'Construct root containers with new Container() and create child scopes with container.createRequestScope().'
+      });
+    }
+    const childScope = Container.#childScopeConstruction;
+    this.parent = childScope?.parent;
+    this.requestScopeEnabled = childScope?.requestScopeEnabled ?? false;
+    this.singletonCache = childScope?.singletonCache ?? new Map();
+    registerMultiContributionResolver(this, (token, contributionIndex) => this.resolveMultiContribution(token, contributionIndex));
+  }
+  static #createChildScope(construction) {
+    const parentConstruction = Container.#childScopeConstruction;
+    Container.#childScopeConstruction = construction;
+    try {
+      return new Container();
+    } finally {
+      Container.#childScopeConstruction = parentConstruction;
+    }
   }
 
   /**
@@ -179,10 +280,16 @@ export class Container {
    * set — the whole set is replaced. If you need to preserve other entries, re-register them
    * together with the replacement in one `override()` call.
    *
+   * **Batch atomicity**: the whole batch is validated before any registration or cache is touched,
+   * so a rejected `override()` call leaves every provider, cached instance, and disposal ownership
+   * exactly as it was before the call.
+   *
    * @param providers Provider definitions that should replace existing registrations for each token.
    * @returns The same container instance for fluent override chains.
    * @throws {ContainerResolutionError} When called after the container was disposed.
+   * @throws {ScopeMismatchError} When a request-scope override would introduce a new singleton token.
    * @throws {InvalidProviderError} When a provider definition is structurally invalid.
+   * @throws {DuplicateProviderError} When one token mixes single and multi replacements or repeats a single replacement.
    */
   override(...providers) {
     if (this.isDisposedInHierarchy()) {
@@ -200,6 +307,19 @@ export class Container {
       }
       normalizedByToken.set(normalized.provide, [normalized]);
     }
+    if (this.requestScopeEnabled) {
+      for (const [token, normalizedProviders] of normalizedByToken) {
+        const introducesSingleton = normalizedProviders.some(normalized => normalized.scope === Scope.DEFAULT);
+        if (introducesSingleton && !this.has(token)) {
+          throw new ScopeMismatchError(`Singleton provider ${formatTokenName(token)} cannot be introduced by override() on a request-scope container.`, {
+            token,
+            scope: 'singleton',
+            hint: 'Register it on the root container before creating the request scope, or register a request/transient provider in the request scope.'
+          });
+        }
+      }
+    }
+    const plannedOverrides = new Map();
     for (const [token, normalizedProviders] of normalizedByToken) {
       const firstProvider = normalizedProviders[0];
       if (!firstProvider) {
@@ -212,6 +332,17 @@ export class Container {
       if (!containsMultiProvider && normalizedProviders.length > 1) {
         throw new DuplicateProviderError(token);
       }
+      plannedOverrides.set(token, {
+        containsMultiProvider,
+        firstProvider,
+        normalizedProviders
+      });
+    }
+    for (const [token, {
+      containsMultiProvider,
+      firstProvider,
+      normalizedProviders
+    }] of plannedOverrides) {
       this.invalidateAffectedCachedEntriesInHierarchy(token);
       this.registrations.delete(token);
       this.multiRegistrations.delete(token);
@@ -282,10 +413,12 @@ export class Container {
       setMultiSingleton: (provider, promise) => {
         this.multiSingletonCache.set(provider, promise);
         multiSingletonCacheSnapshot.set(provider, promise);
+        this.trackCacheMaterialization(promise);
       },
       setSingleton: (token, promise) => {
         this.singletonCache.set(token, promise);
         singletonCacheSnapshot.set(token, promise);
+        this.trackCacheMaterialization(promise);
       }
     });
   }
@@ -323,7 +456,11 @@ export class Container {
         hint: 'Create request scopes before calling container.dispose().'
       });
     }
-    return new Container(this, true, this.root().singletonCache);
+    return Container.#createChildScope({
+      parent: this,
+      requestScopeEnabled: true,
+      singletonCache: this.root().singletonCache
+    });
   }
 
   /**
@@ -346,40 +483,76 @@ export class Container {
     await this.assertStaleDisposalsSettled();
     return this.resolveWithChain(token, [], new Set());
   }
+  async resolveMultiContribution(token, contributionIndex) {
+    if (this.isDisposedInHierarchy()) {
+      throw new ContainerResolutionError('Container has been disposed and can no longer resolve providers.', {
+        token,
+        hint: 'Ensure all resolves complete before calling container.dispose().'
+      });
+    }
+    await this.assertStaleDisposalsSettled();
+    const providers = this.collectMultiProviders(token);
+    const provider = providers[contributionIndex];
+    if (!provider) {
+      throw new ContainerResolutionError(`Multi-provider contribution ${contributionIndex} is not registered for ${formatTokenName(token)}.`, {
+        token,
+        hint: 'Resolve a contribution index returned by the registered multi-provider order.'
+      });
+    }
+    this.assertSingletonDependencyScopes(provider);
+    return await this.withTokenInChain(token, [], new Set(), async (chain, activeTokens) => this.resolveMultiProviderInstance(provider, chain, activeTokens));
+  }
 
   /**
    * Disposes cached instances and nested request scopes.
    *
+   * Concurrent callers share the active disposal attempt. After a failed attempt,
+   * a later explicit call retries only `onDestroy()` hooks that did not complete;
+   * successfully completed hooks are never repeated. Disposal remains terminal
+   * for registration, resolution, overrides, and child-scope creation. A directly
+   * disposed child owns its remaining retries after that attempt settles, while a
+   * parent-started failed attempt remains owned by the parent hierarchy.
+   *
    * @returns A promise that settles after all cached disposable instances are torn down.
    * @throws {Error} Propagates one or more disposal errors (`AggregateError` when multiple failures occur).
    */
   async dispose() {
+    await this.disposeWithOrigin('direct');
+  }
+  async disposeFromParent() {
+    await this.disposeWithOrigin('parent');
+  }
+  async disposeWithOrigin(origin) {
     if (this.disposePromise) {
       await this.disposePromise;
       return;
     }
     this.disposed = true;
     this.advanceGraphRevision();
-    this.disposePromise = this.disposeAll();
+    const activeDispose = this.disposeAll(origin);
+    this.disposePromise = activeDispose;
     try {
-      await this.disposePromise;
+      await activeDispose;
+      if (this.disposePromise === activeDispose && this.hasRetainedStaleDisposalTasksInSubtree()) {
+        this.disposePromise = undefined;
+      }
     } catch (error) {
       this.disposePromise = undefined;
       throw error;
     }
   }
-  async disposeAll() {
+  async disposeAll(origin) {
     const errors = [];
+    let completed = false;
     try {
       // Dispose all live request-scope children before tearing down this scope's cache.
       if (this.childScopes && this.childScopes.size > 0) {
-        const childResults = await Promise.allSettled(Array.from(this.childScopes).map(child => child.dispose()));
+        const childResults = await Promise.allSettled(Array.from(this.childScopes).map(child => child.disposeFromParent()));
         for (const result of childResults) {
           if (result.status === 'rejected') {
             this.collectDisposalError(result.reason, errors);
           }
         }
-        this.childScopes.clear();
       }
       try {
         await this.disposeCache(this.disposalCacheEntries());
@@ -387,8 +560,13 @@ export class Container {
         this.collectDisposalError(error, errors);
       }
       this.throwDisposalErrors(errors);
+      completed = true;
     } finally {
-      if (this.parent && this.trackedByParent) {
+      const retainsStaleRetries = this.hasRetainedStaleDisposalTasksInSubtree();
+      if ((origin === 'direct' || completed && !retainsStaleRetries) && this.parent && this.trackedByParent) {
+        if (origin === 'direct') {
+          this.releaseNonOwnerStaleTaskObserversInSubtree();
+        }
         this.parent.childScopes?.delete(this);
         this.trackedByParent = false;
       }
@@ -522,7 +700,12 @@ export class Container {
     }
     const cachedInstance = this.getCachedScopedOrSingletonInstance(provider);
     if (cachedInstance) {
-      return await cachedInstance;
+      const releasePendingResolution = linkPendingResolution(cachedInstance, activeTokens, token);
+      try {
+        return await cachedInstance;
+      } finally {
+        releasePendingResolution?.();
+      }
     }
     return await this.withTokenInChain(token, chain, activeTokens, async (c, at) => this.resolveScopedOrSingletonInstance(provider, c, at));
   }
@@ -562,16 +745,29 @@ export class Container {
     if (provider.scope === 'transient') {
       return await this.instantiate(provider, chain, activeTokens);
     }
-    if (this.shouldResolveMultiProviderFromRoot(provider)) {
-      return await this.root().resolveMultiProviderInstance(provider, chain, activeTokens);
+    const cacheOwner = this.cacheOwnerFor(provider);
+    if (cacheOwner !== this) {
+      return await cacheOwner.resolveMultiProviderInstance(provider, chain, activeTokens);
     }
     const cache = this.multiCacheFor(provider);
-    if (!cache.has(provider)) {
-      const promise = this.instantiate(provider, chain, activeTokens);
-      cache.set(provider, promise);
-      promise.catch(() => cache.delete(provider));
-    }
-    return await cache.get(provider);
+    const cachedInstance = cache.get(provider);
+    if (cachedInstance) {
+      const releasePendingResolution = linkPendingResolution(cachedInstance, activeTokens, provider.provide);
+      return releasePendingResolution ? cachedInstance.finally(releasePendingResolution) : cachedInstance;
+    }
+    let promise;
+    promise = this.instantiate(provider, chain, activeTokens).then(value => {
+      untrackPendingResolution(promise, activeTokens);
+      return value;
+    }, error => {
+      cache.delete(provider);
+      untrackPendingResolution(promise, activeTokens);
+      throw error;
+    });
+    trackPendingResolution(promise, activeTokens);
+    cache.set(provider, promise);
+    this.trackCacheMaterialization(promise);
+    return promise;
   }
   resolveExistingProviderTarget(provider) {
     if (provider.type !== 'existing') {
@@ -580,33 +776,48 @@ export class Container {
     return provider.useExisting;
   }
   async resolveScopedOrSingletonInstance(provider, chain, activeTokens) {
-    if (this.shouldResolveFromRoot(provider)) {
-      return await this.root().resolveScopedOrSingletonInstance(provider, chain, activeTokens);
+    const cacheOwner = this.cacheOwnerFor(provider);
+    if (cacheOwner !== this) {
+      return await cacheOwner.resolveScopedOrSingletonInstance(provider, chain, activeTokens);
     }
     const cache = this.cacheFor(provider);
-    if (!cache.has(provider.provide)) {
-      const promise = this.instantiate(provider, chain, activeTokens).catch(error => {
-        cache.delete(provider.provide);
-        throw error;
-      });
-      cache.set(provider.provide, promise);
-    }
-    return cache.get(provider.provide);
+    const cachedInstance = cache.get(provider.provide);
+    if (cachedInstance) {
+      const releasePendingResolution = linkPendingResolution(cachedInstance, activeTokens, provider.provide);
+      return releasePendingResolution ? cachedInstance.finally(releasePendingResolution) : cachedInstance;
+    }
+    let promise;
+    promise = this.instantiate(provider, chain, activeTokens).then(value => {
+      untrackPendingResolution(promise, activeTokens);
+      return value;
+    }, error => {
+      cache.delete(provider.provide);
+      untrackPendingResolution(promise, activeTokens);
+      throw error;
+    });
+    trackPendingResolution(promise, activeTokens);
+    cache.set(provider.provide, promise);
+    this.trackCacheMaterialization(promise);
+    return promise;
   }
   getCachedScopedOrSingletonInstance(provider) {
     if (provider.scope !== Scope.DEFAULT) {
       return undefined;
     }
-    if (this.shouldResolveFromRoot(provider)) {
-      return this.root().getCachedScopedOrSingletonInstance(provider);
+    const cacheOwner = this.cacheOwnerFor(provider);
+    if (cacheOwner !== this) {
+      return cacheOwner.getCachedScopedOrSingletonInstance(provider);
     }
     return this.cacheFor(provider).get(provider.provide);
   }
-  shouldResolveFromRoot(provider) {
-    return provider.scope === Scope.DEFAULT && this.requestScopeEnabled && !this.registrations.has(provider.provide);
-  }
-  shouldResolveMultiProviderFromRoot(provider) {
-    return provider.scope === Scope.DEFAULT && this.requestScopeEnabled && !this.hasLocalMultiProvider(provider);
+  cacheOwnerFor(provider) {
+    if (provider.scope !== Scope.DEFAULT || !this.requestScopeEnabled) {
+      return this;
+    }
+    if (this.registrations.get(provider.provide) === provider || this.hasLocalMultiProvider(provider)) {
+      return this;
+    }
+    return this.parent?.cacheOwnerFor(provider) ?? this;
   }
   async resolveDepToken(depEntry, chain, activeTokens) {
     if (isOptionalToken(depEntry)) {
@@ -726,15 +937,20 @@ export class Container {
   }
   async disposeCache(entries) {
     const errors = [];
+    const retryableStaleTasks = this.retainedStaleDisposalTasks();
+    const attemptedStaleInstances = new Set();
     try {
       await this.assertStaleDisposalsSettled();
     } catch (error) {
       this.collectDisposalError(error, errors);
     }
+    errors.push(...(await this.retryFailedStaleDisposals(retryableStaleTasks, attemptedStaleInstances)));
     const {
-      disposables,
+      disposables: materializedDisposables,
       errors: resolutionErrors
     } = await this.collectDisposableInstances(entries);
+    const disposalCandidates = this.pendingDisposables.length > 0 ? this.pendingDisposables : materializedDisposables;
+    const disposables = disposalCandidates.filter(instance => !attemptedStaleInstances.has(instance));
     errors.push(...resolutionErrors);
     errors.push(...(await this.disposeInstancesInReverseOrder(disposables)));
     this.clearDisposalCaches();
@@ -744,13 +960,18 @@ export class Container {
     const disposables = [];
     const seenInstances = new Set();
     const errors = [];
+    const activePromises = new Set(entries.map(([, promise]) => promise));
     const settled = await Promise.allSettled(entries.map(([, p]) => p));
     for (const result of settled) {
       if (result.status === 'rejected') {
         errors.push(result.reason);
+      }
+    }
+    for (const promise of this.materializedCachePromises) {
+      if (!activePromises.has(promise)) {
         continue;
       }
-      const instance = result.value;
+      const instance = await promise;
       if (this.isDisposable(instance) && !seenInstances.has(instance)) {
         seenInstances.add(instance);
         disposables.push(instance);
@@ -763,16 +984,20 @@ export class Container {
   }
   async disposeInstancesInReverseOrder(disposables) {
     const errors = [];
+    const pendingDisposables = [];
     for (const instance of [...disposables].reverse()) {
       try {
         await instance.onDestroy();
       } catch (error) {
         errors.push(error);
+        pendingDisposables.unshift(instance);
       }
     }
+    this.pendingDisposables.splice(0, this.pendingDisposables.length, ...pendingDisposables);
     return errors;
   }
   clearDisposalCaches() {
+    this.materializedCachePromises.length = 0;
     if (this.parent) {
       this.requestCache?.clear();
       this.multiRequestCache?.clear();
@@ -783,6 +1008,9 @@ export class Container {
     this.multiSingletonCache.clear();
     this.clearResolutionPlanCaches();
   }
+  trackCacheMaterialization(promise) {
+    void promise.then(() => this.materializedCachePromises.push(promise), () => undefined);
+  }
   currentLineageRevision() {
     const parentRevision = this.parent?.currentLineageRevision();
     return parentRevision ? `${parentRevision}/${this.graphRevision}` : String(this.graphRevision);
@@ -813,38 +1041,118 @@ export class Container {
   }
   async assertStaleDisposalsSettled() {
     const errors = [];
-    while (this.staleDisposalTasks.size > 0) {
-      const tasks = Array.from(this.staleDisposalTasks);
+    const settled = new Set();
+    while (true) {
+      const tasks = Array.from(this.staleDisposalTasks).filter(task => !settled.has(task));
+      if (tasks.length === 0) {
+        break;
+      }
       await Promise.all(tasks.map(task => task.promise));
       for (const task of tasks) {
-        this.staleDisposalTasks.delete(task);
-        if (task.failed && !task.errorConsumed) {
+        settled.add(task);
+        if (!task.failed) {
+          this.staleDisposalTasks.delete(task);
+          continue;
+        }
+
+        // A rejected materialization has no hook to retry. Deliver its error
+        // once, then release it from every observer's stale-task ledger.
+        if (!task.errorConsumed) {
           task.errorConsumed = true;
           errors.push(task.error);
         }
+        if (!task.retryInstance) {
+          for (const observer of task.observers) {
+            observer.staleDisposalTasks.delete(task);
+          }
+        }
       }
     }
     this.throwDisposalErrors(errors);
   }
+  retainedStaleDisposalTasks() {
+    // Only the scheduling container retries a stale hook, and only when the
+    // failure was already delivered to an earlier caller. A failure first
+    // surfaced by this attempt is reported, not retried within the same pass.
+    return Array.from(this.staleDisposalTasks).filter(task => task.retryOwner === this && task.failed && task.errorConsumed);
+  }
+  hasRetainedStaleDisposalTasksInSubtree() {
+    return this.retainedStaleDisposalTasks().length > 0 || Array.from(this.childScopes ?? []).some(childScope => childScope.hasRetainedStaleDisposalTasksInSubtree());
+  }
+  releaseNonOwnerStaleTaskObservers() {
+    for (const task of this.staleDisposalTasks) {
+      if (task.retryOwner !== this) {
+        continue;
+      }
+      for (const observer of task.observers) {
+        if (observer !== this) {
+          observer.staleDisposalTasks.delete(task);
+        }
+      }
+    }
+  }
+  releaseNonOwnerStaleTaskObserversInSubtree() {
+    this.releaseNonOwnerStaleTaskObservers();
+    for (const childScope of this.childScopes ?? []) {
+      childScope.releaseNonOwnerStaleTaskObserversInSubtree();
+    }
+  }
+  async retryFailedStaleDisposals(tasks, attemptedInstances) {
+    const errors = [];
+    for (const task of tasks) {
+      const instance = task.retryInstance;
+      if (!task.failed || !instance) {
+        continue;
+      }
+      attemptedInstances.add(instance);
+      try {
+        await instance.onDestroy();
+        task.failed = false;
+        task.retryInstance = undefined;
+        for (const observer of task.observers) {
+          observer.staleDisposalTasks.delete(task);
+        }
+      } catch (error) {
+        task.error = error;
+        task.errorConsumed = true;
+        errors.push(error);
+      }
+    }
+    return errors;
+  }
   scheduleStaleDisposal(instancePromise, staleDisposalOwner) {
     const observers = staleDisposalOwner === this ? [this] : [this, staleDisposalOwner];
     const task = {
       error: undefined,
       errorConsumed: false,
       failed: false,
-      promise: Promise.resolve()
+      observers,
+      promise: Promise.resolve(),
+      retryInstance: undefined,
+      retryOwner: this
     };
     task.promise = (async () => {
+      let instance;
       try {
-        const instance = await instancePromise;
-        if (this.isDisposable(instance)) {
-          await instance.onDestroy();
-        }
+        instance = await instancePromise;
       } catch (error) {
         task.error = error;
         task.failed = true;
+        return;
+      }
+      if (!this.isDisposable(instance)) {
+        return;
+      }
+      try {
+        await instance.onDestroy();
+      } catch (error) {
+        task.error = error;
+        task.failed = true;
+        task.retryInstance = instance;
       }
     })().finally(() => {
+      const retainedMaterializations = this.materializedCachePromises.filter(promise => promise !== instancePromise);
+      this.materializedCachePromises.splice(0, this.materializedCachePromises.length, ...retainedMaterializations);
       if (!task.failed) {
         for (const observer of observers) {
           observer.staleDisposalTasks.delete(task);
@@ -934,6 +1242,10 @@ export class Container {
     }
     visited.add(token);
     try {
+      const multiRequestScopedToken = this.findRequestScopedMultiContribution(token, visited);
+      if (multiRequestScopedToken) {
+        return multiRequestScopedToken;
+      }
       const provider = this.resolveEffectiveProvider(token);
       if (provider) {
         if (provider.scope === Scope.REQUEST) {
@@ -953,6 +1265,28 @@ export class Container {
       visited.delete(token);
     }
   }
+  findRequestScopedMultiContribution(token, visited) {
+    const aliasChain = new Set();
+    let currentToken = token;
+    while (!aliasChain.has(currentToken)) {
+      aliasChain.add(currentToken);
+      for (const multiProvider of this.collectMultiProviders(currentToken)) {
+        if (multiProvider.scope === Scope.REQUEST) {
+          return multiProvider.provide;
+        }
+        const requestScopedToken = multiProvider.type === 'existing' && multiProvider.useExisting !== undefined ? this.findRequestScopedDependencyToken(multiProvider.useExisting, visited) : this.findRequestScopedDependency(multiProvider.inject, visited);
+        if (requestScopedToken) {
+          return requestScopedToken;
+        }
+      }
+      const aliasProvider = this.lookupProvider(currentToken);
+      if (aliasProvider?.type !== 'existing' || aliasProvider.useExisting === undefined) {
+        return undefined;
+      }
+      currentToken = aliasProvider.useExisting;
+    }
+    return undefined;
+  }
   resolveEffectiveProvider(token, visited = new Set(), chain = []) {
     const cacheable = visited.size === 0 && chain.length === 0;
     if (cacheable) {

package/dist/errors.d.ts

@@ -48,7 +48,8 @@ export declare class ScopeMismatchError extends FluoCodeError {
  *
  * @remarks
  * The formatted message includes the full dependency path plus a first-party hint that points callers toward
- * extracting shared logic or using `forwardRef()` for intentional cycle deferral.
+ * extracting shared logic, introducing a mediator, or moving the interaction to a later boundary.
+ * `forwardRef()` only defers declaration-time token lookup and cannot resolve a true constructor cycle.
  */
 export declare class CircularDependencyError extends FluoCodeError {
     constructor(chain: readonly unknown[], detail?: string);

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAmB,MAAM,cAAc,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAgCD;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,aAAa;gBACzC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;gBAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;;;;GAKG;AACH,qBAAa,2BAA4B,SAAQ,aAAa;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,aAAa;gBAC5C,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM;CAWvD;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;gBAC3C,KAAK,EAAE,OAAO;CAW3B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAmB,MAAM,cAAc,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAgCD;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,aAAa;gBACzC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;gBAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;;;;GAKG;AACH,qBAAa,2BAA4B,SAAQ,aAAa;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,aAAa;gBAC5C,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM;CAWvD;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;gBAC3C,KAAK,EAAE,OAAO;CAW3B"}