@fluojs/di 1.1.0 → 3.0.0

package/dist/container.js

@@ -1,138 +1,191 @@
-import { InvariantError, formatTokenName } from '@fluojs/core';
+import { formatTokenName, InvariantError } from '@fluojs/core';
 import { getClassDiMetadata } from '@fluojs/core/internal';
-import { CircularDependencyError, ContainerResolutionError, DuplicateProviderError, InvalidProviderError, RequestScopeResolutionError, ScopeMismatchError } from './errors.js';
-import { Scope, isForwardRef, isOptionalToken } from './types.js';
+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';
 
 /**
- * Public read/write seam for framework-owned testing and tooling that need to
+ * Factory provider resolution mode recorded after a factory returns either synchronously or through a promise.
+ */
+
+/**
+ * Controlled cache adoption seam for framework-owned testing and tooling that
+ * need synchronous helpers to preserve container-owned singleton disposal.
+ */
+
+/**
+ * Read-only factory resolution diagnostics recorded by container-owned factory
+ * instantiation paths.
+ */
+
+/**
+ * Public read-only seam for framework-owned testing and tooling that need to
  * inspect a container's resolved provider graph without depending on private
  * field names or structural casts.
  */
 
-function isClassConstructor(value) {
-  return typeof value === 'function';
-}
-function isValueProvider(value) {
-  return typeof value === 'object' && value !== null && 'useValue' in value;
-}
-function isFactoryProvider(value) {
-  return typeof value === 'object' && value !== null && 'useFactory' in value;
-}
-function isClassProvider(value) {
-  return typeof value === 'object' && value !== null && 'useClass' in value;
-}
-function isExistingProvider(value) {
-  return typeof value === 'object' && value !== null && 'useExisting' in value;
-}
-function assertProviderToken(provider) {
-  if (!('provide' in provider) || provider.provide == null) {
-    throw new InvalidProviderError('Provider object must include a non-null provide token.');
+class ReadonlyMapView {
+  #source;
+  [Symbol.toStringTag] = 'Map';
+  constructor(source) {
+    this.#source = source;
+  }
+  get size() {
+    return this.#source.size;
+  }
+  entries() {
+    return this.#source.entries();
+  }
+  forEach(callbackfn, thisArg) {
+    for (const [key, value] of this.#source) {
+      callbackfn.call(thisArg, value, key, this);
+    }
+  }
+  get(key) {
+    return this.#source.get(key);
+  }
+  has(key) {
+    return this.#source.has(key);
+  }
+  keys() {
+    return this.#source.keys();
+  }
+  values() {
+    return this.#source.values();
+  }
+  [Symbol.iterator]() {
+    return this.entries();
   }
 }
-function assertProviderStrategy(provider) {
-  const strategyCount = Number('useValue' in provider) + Number('useFactory' in provider) + Number('useClass' in provider) + Number('useExisting' in provider);
-  if (strategyCount !== 1) {
-    throw new InvalidProviderError('Provider object must declare exactly one of useValue, useFactory, useClass, or useExisting.');
+class ReadonlyMultiRegistrationMapView {
+  #source;
+  [Symbol.toStringTag] = 'Map';
+  constructor(source) {
+    this.#source = source;
   }
+  get size() {
+    return this.#source.size;
+  }
+  *entries() {
+    for (const [token, providers] of this.#source) {
+      yield [token, Object.freeze([...providers])];
+    }
+  }
+  forEach(callbackfn, thisArg) {
+    for (const [key, value] of this.entries()) {
+      callbackfn.call(thisArg, value, key, this);
+    }
+  }
+  get(key) {
+    const providers = this.#source.get(key);
+    return providers ? Object.freeze([...providers]) : undefined;
+  }
+  has(key) {
+    return this.#source.has(key);
+  }
+  keys() {
+    return this.#source.keys();
+  }
+  *values() {
+    for (const providers of this.#source.values()) {
+      yield Object.freeze([...providers]);
+    }
+  }
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+}
+function isPromiseLike(value) {
+  return (typeof value === 'object' || typeof value === 'function') && value !== null && typeof value.then === 'function';
 }
-function assertObjectProvider(provider) {
-  assertProviderToken(provider);
-  assertProviderStrategy(provider);
+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 normalizeInjectToken(token) {
-  if (token == null) {
-    throw new InvalidProviderError('Inject token must not be null or undefined. Check that all tokens in @Inject(...) are defined at the point of decoration (forward-reference cycles require forwardRef()).');
+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);
   }
-  return token;
 }
-function normalizeProvider(provider) {
-  if (isClassConstructor(provider)) {
-    const metadata = getClassDiMetadata(provider);
-    return {
-      inject: (metadata?.inject ?? []).map(normalizeInjectToken),
-      provide: provider,
-      scope: metadata?.scope ?? Scope.DEFAULT,
-      type: 'class',
-      useClass: provider
-    };
+function findPendingResolutionPath(start, target, visited) {
+  if (start === target) {
+    return [start];
   }
-  if (isValueProvider(provider)) {
-    assertObjectProvider(provider);
-    return {
-      inject: [],
-      multi: provider.multi,
-      provide: provider.provide,
-      scope: Scope.DEFAULT,
-      type: 'value',
-      useValue: provider.useValue
-    };
+  if (visited.has(start)) {
+    return undefined;
   }
-  if (isFactoryProvider(provider)) {
-    assertObjectProvider(provider);
-    if (typeof provider.useFactory !== 'function') {
-      throw new InvalidProviderError('Factory provider useFactory must be a function.', {
-        token: provider.provide
-      });
+  visited.add(start);
+  for (const dependency of pendingResolutionContexts.get(start)?.dependencies.keys() ?? []) {
+    const path = findPendingResolutionPath(dependency, target, visited);
+    if (path) {
+      return [start, ...path];
     }
-    const metadata = provider.resolverClass ? getClassDiMetadata(provider.resolverClass) : undefined;
-    return {
-      inject: (provider.inject ?? []).map(normalizeInjectToken),
-      multi: provider.multi,
-      provide: provider.provide,
-      scope: provider.scope ?? metadata?.scope ?? Scope.DEFAULT,
-      type: 'factory',
-      useFactory: provider.useFactory
-    };
   }
-  if (isClassProvider(provider)) {
-    assertObjectProvider(provider);
-    if (typeof provider.useClass !== 'function') {
-      throw new InvalidProviderError('Class provider useClass must be a constructor.', {
-        token: provider.provide
-      });
-    }
-    const metadata = getClassDiMetadata(provider.useClass);
-    return {
-      inject: (provider.inject ?? metadata?.inject ?? []).map(normalizeInjectToken),
-      multi: provider.multi,
-      provide: provider.provide,
-      scope: provider.scope ?? metadata?.scope ?? Scope.DEFAULT,
-      type: 'class',
-      useClass: provider.useClass
-    };
+  return undefined;
+}
+function linkPendingResolution(promise, activeTokens, token) {
+  const owner = pendingResolutionOwners.get(promise);
+  if (!owner || activeTokens.size === 0) {
+    return undefined;
   }
-  if (isExistingProvider(provider)) {
-    assertObjectProvider(provider);
-    if (provider.useExisting == null) {
-      throw new InvalidProviderError('Alias provider useExisting must be a non-null token.', {
-        token: provider.provide
-      });
+  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;
     }
-    return {
-      inject: [],
-      provide: provider.provide,
-      scope: Scope.DEFAULT,
-      type: 'existing',
-      useExisting: provider.useExisting
-    };
-  }
-  throw new InvalidProviderError('Unsupported provider type.');
+    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();
-  staleDisposalErrors = [];
   singletonCache;
   forwardRefTokenCache = new WeakMap();
+  factoryResolutionKinds = new WeakMap();
   providerLookupPlanCache = new Map();
   multiProviderPlanCache = new Map();
   requestScopeVerdictPlanCache = new Map();
@@ -140,12 +193,40 @@ export class Container {
   childScopes;
   disposePromise;
   disposed = false;
-  trackedByRoot = 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;
+    }
   }
 
   /**
@@ -199,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()) {
@@ -220,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) {
@@ -232,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);
@@ -263,21 +374,61 @@ export class Container {
    *
    * This method is the supported introspection seam for packages such as
    * `@fluojs/testing`; callers should prefer ordinary `has(...)` and
-   * `resolve(...)` unless they need to preserve container cache ownership while
-   * implementing a framework-level helper.
+   * `resolve(...)` unless they need read-only graph/cache visibility while
+   * implementing a framework-level helper. Cache adoption for synchronous
+   * helpers goes through `cacheOwner`; the returned maps are not mutable
+   * container internals.
    *
-   * @returns Provider registrations and resolution caches for this container scope.
+   * @returns Read-only provider registrations and resolution caches for this container scope.
    */
   inspectResolutionState() {
+    const registrations = new Map(this.registrations);
+    const multiRegistrations = new Map(Array.from(this.multiRegistrations, ([token, providers]) => [token, Object.freeze([...providers])]));
+    const multiSingletonCache = new Map(this.multiSingletonCache);
+    const singletonCache = new Map(this.singletonCache);
     return {
+      cacheOwner: this.createCacheOwner(singletonCache, multiSingletonCache),
+      factoryResolutionKinds: this.createFactoryResolutionState(),
       parent: this.parent?.inspectResolutionState(),
-      registrations: this.registrations,
-      multiRegistrations: this.multiRegistrations,
-      multiSingletonCache: this.multiSingletonCache,
+      registrations: new ReadonlyMapView(registrations),
+      multiRegistrations: new ReadonlyMultiRegistrationMapView(multiRegistrations),
+      multiSingletonCache: new ReadonlyMapView(multiSingletonCache),
       requestScopeEnabled: this.requestScopeEnabled,
-      singletonCache: this.singletonCache
+      singletonCache: new ReadonlyMapView(singletonCache)
     };
   }
+  createCacheOwner(singletonCacheSnapshot, multiSingletonCacheSnapshot) {
+    return Object.freeze({
+      deleteMultiSingleton: provider => {
+        this.multiSingletonCache.delete(provider);
+        multiSingletonCacheSnapshot.delete(provider);
+      },
+      deleteSingleton: token => {
+        this.singletonCache.delete(token);
+        singletonCacheSnapshot.delete(token);
+      },
+      recordFactoryResolution: (provider, kind) => {
+        this.root().factoryResolutionKinds.set(provider, kind);
+      },
+      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);
+      }
+    });
+  }
+  createFactoryResolutionState() {
+    const root = this.root();
+    return Object.freeze({
+      get: provider => root.factoryResolutionKinds.get(provider),
+      has: provider => root.factoryResolutionKinds.has(provider)
+    });
+  }
 
   /**
    * Returns whether resolving a token may require a request-scope container.
@@ -305,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
+    });
   }
 
   /**
@@ -325,42 +480,79 @@ export class Container {
         hint: 'Ensure all resolves complete before calling container.dispose().'
       });
     }
+    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 first (root only)
-      if (!this.parent && this.childScopes && this.childScopes.size > 0) {
-        const childResults = await Promise.allSettled(Array.from(this.childScopes).map(child => child.dispose()));
+      // 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.disposeFromParent()));
         for (const result of childResults) {
           if (result.status === 'rejected') {
             this.collectDisposalError(result.reason, errors);
           }
         }
-        this.childScopes.clear();
       }
       try {
         await this.disposeCache(this.disposalCacheEntries());
@@ -368,10 +560,15 @@ export class Container {
         this.collectDisposalError(error, errors);
       }
       this.throwDisposalErrors(errors);
+      completed = true;
     } finally {
-      if (this.parent && this.trackedByRoot) {
-        this.root().childScopes?.delete(this);
-        this.trackedByRoot = false;
+      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;
       }
     }
   }
@@ -503,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));
   }
@@ -543,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') {
@@ -561,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)) {
@@ -617,13 +847,13 @@ export class Container {
     return this.parent ? this.parent.root() : this;
   }
   ensureTrackedRequestScope() {
-    if (!this.requestScopeEnabled || !this.parent || this.trackedByRoot) {
+    if (!this.requestScopeEnabled || !this.parent || this.trackedByParent) {
       return;
     }
-    const root = this.root();
-    root.childScopes ??= new Set();
-    root.childScopes.add(this);
-    this.trackedByRoot = true;
+    this.parent.ensureTrackedRequestScope();
+    this.parent.childScopes ??= new Set();
+    this.parent.childScopes.add(this);
+    this.trackedByParent = true;
   }
   requestCacheForWrite() {
     this.ensureTrackedRequestScope();
@@ -706,12 +936,22 @@ export class Container {
     return entries;
   }
   async disposeCache(entries) {
-    await this.waitForStaleDisposalTasks();
+    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,
-      errors
+      disposables: materializedDisposables,
+      errors: resolutionErrors
     } = await this.collectDisposableInstances(entries);
-    errors.push(...this.staleDisposalErrors.splice(0, this.staleDisposalErrors.length));
+    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();
     this.throwDisposalErrors(errors);
@@ -720,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);
@@ -739,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();
@@ -759,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);
@@ -787,26 +1039,129 @@ export class Container {
     this.requestScopeVerdictPlanCache.clear();
     this.effectiveProviderPlanCache.clear();
   }
-  async waitForStaleDisposalTasks() {
-    while (this.staleDisposalTasks.size > 0) {
-      await Promise.all(Array.from(this.staleDisposalTasks));
+  async assertStaleDisposalsSettled() {
+    const errors = [];
+    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) {
+        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());
   }
-  scheduleStaleDisposal(instancePromise) {
-    let task;
-    task = (async () => {
+  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 {
-        const instance = await instancePromise;
-        if (this.isDisposable(instance)) {
-          await instance.onDestroy();
+        await instance.onDestroy();
+        task.failed = false;
+        task.retryInstance = undefined;
+        for (const observer of task.observers) {
+          observer.staleDisposalTasks.delete(task);
         }
       } catch (error) {
-        this.staleDisposalErrors.push(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,
+      observers,
+      promise: Promise.resolve(),
+      retryInstance: undefined,
+      retryOwner: this
+    };
+    task.promise = (async () => {
+      let instance;
+      try {
+        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(() => {
-      this.staleDisposalTasks.delete(task);
+      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);
+        }
+      }
     });
-    this.staleDisposalTasks.add(task);
+    for (const observer of observers) {
+      observer.staleDisposalTasks.add(task);
+    }
   }
   throwDisposalErrors(errors) {
     if (errors.length === 1) {
@@ -839,7 +1194,9 @@ export class Container {
             throw new InvariantError('Factory provider is missing useFactory.');
           }
           const deps = await this.resolveProviderDeps(provider, chain, activeTokens);
-          return provider.useFactory(...deps);
+          const value = provider.useFactory(...deps);
+          this.root().factoryResolutionKinds.set(provider, isPromiseLike(value) ? 'async' : 'sync');
+          return value;
         }
       case 'class':
         {
@@ -885,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) {
@@ -904,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) {
@@ -959,34 +1342,18 @@ export class Container {
     }
     return deps;
   }
-  invalidateAffectedCachedEntriesInHierarchy(token) {
-    this.invalidateAffectedCachedEntries(token);
-    const childScopes = this.root().childScopes;
-    if (!childScopes) {
-      return;
-    }
-    for (const childScope of childScopes) {
-      if (this.isAncestorOf(childScope)) {
-        childScope.invalidateAffectedCachedEntries(token);
-      }
-    }
-  }
-  isAncestorOf(container) {
-    let current = container.parent;
-    while (current) {
-      if (current === this) {
-        return true;
-      }
-      current = current.parent;
+  invalidateAffectedCachedEntriesInHierarchy(token, staleDisposalOwner = this) {
+    this.invalidateAffectedCachedEntries(token, staleDisposalOwner);
+    for (const childScope of this.childScopes ?? []) {
+      childScope.invalidateAffectedCachedEntriesInHierarchy(token, staleDisposalOwner);
     }
-    return false;
   }
-  invalidateAffectedCachedEntries(token) {
+  invalidateAffectedCachedEntries(token, staleDisposalOwner) {
     for (const [cachedToken, cached] of this.requestCache?.entries() ?? []) {
       if (!this.shouldInvalidateCachedToken(cachedToken, token)) {
         continue;
       }
-      this.scheduleStaleDisposal(cached);
+      this.scheduleStaleDisposal(cached, staleDisposalOwner);
       this.requestCache?.delete(cachedToken);
     }
     if (!this.parent) {
@@ -994,7 +1361,7 @@ export class Container {
         if (!this.shouldInvalidateCachedToken(cachedToken, token)) {
           continue;
         }
-        this.scheduleStaleDisposal(cached);
+        this.scheduleStaleDisposal(cached, staleDisposalOwner);
         this.singletonCache.delete(cachedToken);
       }
     }
@@ -1003,7 +1370,7 @@ export class Container {
         if (!this.shouldInvalidateCachedProvider(provider, token)) {
           continue;
         }
-        this.scheduleStaleDisposal(cached);
+        this.scheduleStaleDisposal(cached, staleDisposalOwner);
         this.multiSingletonCache.delete(provider);
       }
     }
@@ -1015,7 +1382,7 @@ export class Container {
       if (!this.shouldInvalidateCachedProvider(provider, token)) {
         continue;
       }
-      this.scheduleStaleDisposal(cached);
+      this.scheduleStaleDisposal(cached, staleDisposalOwner);
       multiRequestCache.delete(provider);
     }
   }