@navios/di 0.8.0 → 0.9.0

package/lib/{container-YPwvmlK2.d.cts → container-D-0Ho3qL.d.cts}

@@ -1,5 +1,55 @@
 import { ZodObject, ZodOptional, ZodRecord, ZodType, z } from "zod/v4";
 
+//#region src/token/injection-token.d.mts
+type ClassType = new (...args: any[]) => any;
+type ClassTypeWithoutArguments = new () => any;
+type ClassTypeWithArgument<Arg> = new (arg: Arg) => any;
+type ClassTypeWithOptionalArgument<Arg> = new (arg?: Arg) => any;
+type ClassTypeWithInstance<T> = new (...args: any[]) => T;
+type ClassTypeWithInstanceAndArgument<T, Arg> = new (arg: Arg) => T;
+type ClassTypeWithInstanceAndOptionalArgument<T, Arg> = new (arg?: Arg) => T;
+type BaseInjectionTokenSchemaType = ZodObject | ZodRecord;
+type OptionalInjectionTokenSchemaType = ZodOptional<ZodObject> | ZodOptional<ZodRecord>;
+type InjectionTokenSchemaType = BaseInjectionTokenSchemaType | OptionalInjectionTokenSchemaType;
+declare class InjectionToken<T, S extends InjectionTokenSchemaType | unknown = unknown, Required extends boolean = (S extends ZodOptional<ZodObject> ? false : S extends ZodOptional<ZodRecord> ? false : S extends ZodObject ? true : S extends ZodRecord ? true : false)> {
+  readonly name: string | symbol | ClassType;
+  readonly schema: ZodObject | undefined;
+  readonly id: string;
+  private formattedName;
+  constructor(name: string | symbol | ClassType, schema: ZodObject | undefined, customId?: string);
+  static create<T extends ClassType>(name: T): InjectionToken<InstanceType<T>, undefined>;
+  static create<T extends ClassType, Schema extends InjectionTokenSchemaType>(name: T, schema: Schema): Schema['_def']['type'] extends 'ZodOptional' ? InjectionToken<InstanceType<T>, Schema, false> : InjectionToken<InstanceType<T>, Schema, true>;
+  static create<T>(name: string | symbol): InjectionToken<T, undefined>;
+  static create<T, Schema extends InjectionTokenSchemaType>(name: string | any, schema: Schema): InjectionToken<T, Schema>;
+  static bound<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, value: z.input<S>): BoundInjectionToken<T, S>;
+  static factory<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, factory: (ctx: FactoryContext) => Promise<z.input<S>>): FactoryInjectionToken<T, S>;
+  static refineType<T>(token: BoundInjectionToken<any, any>): BoundInjectionToken<T, any>;
+  toString(): string;
+}
+declare class BoundInjectionToken<T, S extends InjectionTokenSchemaType> {
+  readonly token: InjectionToken<T, S>;
+  readonly value: z.input<S>;
+  id: string;
+  name: string | symbol | ClassType;
+  schema: InjectionTokenSchemaType;
+  constructor(token: InjectionToken<T, S>, value: z.input<S>);
+  toString(): string;
+}
+declare class FactoryInjectionToken<T, S extends InjectionTokenSchemaType> {
+  readonly token: InjectionToken<T, S>;
+  readonly factory: (ctx: FactoryContext) => Promise<z.input<S>>;
+  value?: z.input<S>;
+  resolved: boolean;
+  id: string;
+  name: string | symbol | ClassType;
+  schema: InjectionTokenSchemaType;
+  constructor(token: InjectionToken<T, S>, factory: (ctx: FactoryContext) => Promise<z.input<S>>);
+  resolve(ctx: FactoryContext): Promise<z.input<S>>;
+  toString(): string;
+}
+type AnyInjectableType = ClassType | InjectionToken<any, any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any>;
+type InjectionTokenType = InjectionToken<any, any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any>;
+//#endregion
 //#region src/utils/types.d.mts
 type Join<TElements, TSeparator extends string> = TElements extends Readonly<[infer First, ...infer Rest]> ? Rest extends ReadonlyArray<string> ? First extends string ? `${First}${Rest extends [] ? '' : TSeparator}${Join<Rest, TSeparator>}` : never : never : '';
 type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
@@ -19,14 +69,6 @@ interface InjectState {
   requests: InjectRequest[];
 }
 //#endregion
-//#region src/interfaces/factory.interface.d.mts
-interface Factorable<T> {
-  create(ctx?: FactoryContext): Promise<T> | T;
-}
-interface FactorableWithArgs<T, A extends InjectionTokenSchemaType> {
-  create(ctx?: FactoryContext, ...args: [z.output<A>]): Promise<T> | T;
-}
-//#endregion
 //#region src/interfaces/container.interface.d.mts
 /**
  * Interface for dependency injection containers.
@@ -52,6 +94,15 @@ interface IContainer {
    * Checks if a service is registered in the container.
    */
   isRegistered(token: any): boolean;
+  /**
+   * Adds an instance to the container.
+   * Accepts class types, InjectionTokens, and BoundInjectionTokens.
+   * Rejects InjectionTokens with required schemas (use BoundInjectionToken instead).
+   *
+   * @param token The class type, InjectionToken, or BoundInjectionToken to register the instance for
+   * @param instance The instance to store
+   */
+  addInstance<T>(token: ClassType | InjectionToken<T, any> | BoundInjectionToken<T, any>, instance: T): void;
   /**
    * Disposes the container and cleans up all resources.
    */
@@ -69,6 +120,69 @@ interface IContainer {
   tryGetSync<T>(token: any, args?: any): T | null;
 }
 //#endregion
+//#region src/enums/injectable-scope.enum.d.mts
+declare enum InjectableScope {
+  /**
+   * Singleton scope: The instance is created once and shared across the application.
+   */
+  Singleton = "Singleton",
+  /**
+   * Instance scope: A new instance is created for each injection.
+   */
+  Transient = "Transient",
+  /**
+   * Request scope: The instance is created once per request and shared within that request context.
+   */
+  Request = "Request",
+}
+//#endregion
+//#region src/enums/injectable-type.enum.d.mts
+declare enum InjectableType {
+  Class = "Class",
+  Factory = "Factory",
+}
+//#endregion
+//#region src/internal/context/service-initialization-context.d.mts
+/**
+ * Context provided to injectors during service initialization.
+ *
+ * Extends FactoryContext with additional tracking information about
+ * the service being initialized, its dependencies, and scope.
+ * Used for scope upgrade tracking and dependency management.
+ */
+interface ServiceInitializationContext {
+  inject: Injectors['asyncInject'];
+  /**
+   * The container instance for dependency resolution.
+   * This may be either a Container or ScopedContainer.
+   */
+  container: IContainer;
+  addDestroyListener: (listener: () => void) => void;
+  getDestroyListeners: () => (() => void)[];
+  /**
+   * The name of the service being initialized.
+   */
+  serviceName: string;
+  /**
+   * Set of dependency names that this service depends on.
+   * Automatically populated as dependencies are resolved.
+   */
+  dependencies: Set<string>;
+  /**
+   * The scope of the service being initialized.
+   */
+  scope: InjectableScope;
+  /**
+   * Track a dependency that was resolved.
+   * Used for scope upgrade tracking - if a Singleton service
+   * resolves a Request dependency, the scope can be upgraded.
+   *
+   * @param name The name of the dependency
+   * @param scope The scope of the dependency
+   */
+  trackDependency(name: string, scope: InjectableScope): void;
+}
+//#endregion
 //#region src/utils/get-injectors.d.mts
 interface Injectors {
   asyncInject<T extends ClassTypeWithoutArguments>(token: T): InstanceType<T> extends Factorable<infer R> ? Promise<R> : Promise<InstanceType<T>>;
@@ -112,7 +226,7 @@ interface Injectors {
   optional<T>(token: BoundInjectionToken<T, any>): T | null;
   optional<T>(token: FactoryInjectionToken<T, any>): T | null;
   wrapSyncInit(cb: () => any): (injectState?: InjectState) => [any, Promise<any>[], InjectState];
-  provideFactoryContext(context: FactoryContext | null): FactoryContext | null;
+  provideFactoryContext(context: ServiceInitializationContext | null): ServiceInitializationContext | null;
 }
 declare function getInjectors(): Injectors;
 //#endregion
@@ -133,76 +247,12 @@ interface FactoryContext {
   addDestroyListener: (listener: () => void) => void;
 }
 //#endregion
-//#region src/token/injection-token.d.mts
-type ClassType = new (...args: any[]) => any;
-type ClassTypeWithoutArguments = new () => any;
-type ClassTypeWithArgument<Arg> = new (arg: Arg) => any;
-type ClassTypeWithOptionalArgument<Arg> = new (arg?: Arg) => any;
-type ClassTypeWithInstance<T> = new (...args: any[]) => T;
-type ClassTypeWithInstanceAndArgument<T, Arg> = new (arg: Arg) => T;
-type ClassTypeWithInstanceAndOptionalArgument<T, Arg> = new (arg?: Arg) => T;
-type BaseInjectionTokenSchemaType = ZodObject | ZodRecord;
-type OptionalInjectionTokenSchemaType = ZodOptional<ZodObject> | ZodOptional<ZodRecord>;
-type InjectionTokenSchemaType = BaseInjectionTokenSchemaType | OptionalInjectionTokenSchemaType;
-declare class InjectionToken<T, S extends InjectionTokenSchemaType | unknown = unknown, Required extends boolean = (S extends ZodOptional<ZodObject> ? false : S extends ZodOptional<ZodRecord> ? false : S extends ZodObject ? true : S extends ZodRecord ? true : false)> {
-  readonly name: string | symbol | ClassType;
-  readonly schema: ZodObject | undefined;
-  id: `${string}-${string}-${string}-${string}-${string}`;
-  private formattedName;
-  constructor(name: string | symbol | ClassType, schema: ZodObject | undefined);
-  static create<T extends ClassType>(name: T): InjectionToken<InstanceType<T>, undefined>;
-  static create<T extends ClassType, Schema extends InjectionTokenSchemaType>(name: T, schema: Schema): Schema['_def']['type'] extends 'ZodOptional' ? InjectionToken<InstanceType<T>, Schema, false> : InjectionToken<InstanceType<T>, Schema, true>;
-  static create<T>(name: string | symbol): InjectionToken<T, undefined>;
-  static create<T, Schema extends InjectionTokenSchemaType>(name: string | any, schema: Schema): InjectionToken<T, Schema>;
-  static bound<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, value: z.input<S>): BoundInjectionToken<T, S>;
-  static factory<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, factory: (ctx: FactoryContext) => Promise<z.input<S>>): FactoryInjectionToken<T, S>;
-  static refineType<T>(token: BoundInjectionToken<any, any>): BoundInjectionToken<T, any>;
-  toString(): string;
-}
-declare class BoundInjectionToken<T, S extends InjectionTokenSchemaType> {
-  readonly token: InjectionToken<T, S>;
-  readonly value: z.input<S>;
-  id: string;
-  name: string | symbol | ClassType;
-  schema: InjectionTokenSchemaType;
-  constructor(token: InjectionToken<T, S>, value: z.input<S>);
-  toString(): string;
-}
-declare class FactoryInjectionToken<T, S extends InjectionTokenSchemaType> {
-  readonly token: InjectionToken<T, S>;
-  readonly factory: (ctx: FactoryContext) => Promise<z.input<S>>;
-  value?: z.input<S>;
-  resolved: boolean;
-  id: string;
-  name: string | symbol | ClassType;
-  schema: InjectionTokenSchemaType;
-  constructor(token: InjectionToken<T, S>, factory: (ctx: FactoryContext) => Promise<z.input<S>>);
-  resolve(ctx: FactoryContext): Promise<z.input<S>>;
-  toString(): string;
-}
-type AnyInjectableType = ClassType | InjectionToken<any, any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any>;
-type InjectionTokenType = InjectionToken<any, any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any>;
-//#endregion
-//#region src/enums/injectable-scope.enum.d.mts
-declare enum InjectableScope {
-  /**
-   * Singleton scope: The instance is created once and shared across the application.
-   */
-  Singleton = "Singleton",
-  /**
-   * Instance scope: A new instance is created for each injection.
-   */
-  Transient = "Transient",
-  /**
-   * Request scope: The instance is created once per request and shared within that request context.
-   */
-  Request = "Request",
+//#region src/interfaces/factory.interface.d.mts
+interface Factorable<T> {
+  create(ctx?: FactoryContext): Promise<T> | T;
 }
-//#endregion
-//#region src/enums/injectable-type.enum.d.mts
-declare enum InjectableType {
-  Class = "Class",
-  Factory = "Factory",
+interface FactorableWithArgs<T, A extends InjectionTokenSchemaType> {
+  create(ctx?: FactoryContext, ...args: [z.output<A>]): Promise<T> | T;
 }
 //#endregion
 //#region src/token/registry.d.mts
@@ -211,14 +261,17 @@ type FactoryRecord<Instance = any, Schema = any> = {
   originalToken: InjectionToken<Instance, Schema>;
   target: ClassType;
   type: InjectableType;
+  priority: number;
 };
 declare class Registry {
   private readonly parent?;
   private readonly factories;
+  private readonly highestPriority;
   constructor(parent?: Registry | undefined);
   has(token: InjectionToken<any, any>): boolean;
   get<Instance, Schema>(token: InjectionToken<Instance, Schema>): FactoryRecord<Instance, Schema>;
-  set<Instance, Schema>(token: InjectionToken<Instance, Schema>, scope: InjectableScope, target: ClassType, type: InjectableType): void;
+  getAll<Instance, Schema>(token: InjectionToken<Instance, Schema>): FactoryRecord<Instance, Schema>[];
+  set<Instance, Schema>(token: InjectionToken<Instance, Schema>, scope: InjectableScope, target: ClassType, type: InjectableType, priority?: number): void;
   delete(token: InjectionToken<any, any>): void;
   /**
    * Updates the scope of an already registered factory.
@@ -233,6 +286,52 @@ declare class Registry {
 }
 declare const globalRegistry: Registry;
 //#endregion
+//#region src/internal/core/name-resolver.d.mts
+/**
+ * Handles instance name generation with support for requestId and scope.
+ *
+ * Generates unique instance identifiers based on token, arguments, and scope.
+ * Request-scoped services MUST include requestId in their name for proper isolation.
+ */
+declare class NameResolver {
+  private readonly logger;
+  private readonly instanceNameCache;
+  constructor(logger?: Console | null);
+  /**
+   * Generates a unique instance name based on token, arguments, requestId, and scope.
+   *
+   * Name formats:
+   * - Singleton/Transient without args: `${tokenId}`
+   * - Singleton/Transient with args: `${tokenId}:${argsHash}`
+   * - Request without args: `${tokenId}:requestId=${requestId}`
+   * - Request with args: `${tokenId}:requestId=${requestId}:${argsHash}`
+   *
+   * @param token The injection token
+   * @param args Optional arguments
+   * @param requestId Optional request ID (required for request-scoped services)
+   * @param scope Optional scope (used to determine if requestId should be included)
+   * @returns The generated instance name
+   */
+  generateInstanceName(token: InjectionTokenType, args?: any, requestId?: string, scope?: InjectableScope): string;
+  /**
+   * Upgrades an existing instance name to include requestId.
+   * Preserves any args hash that might already be in the name.
+   *
+   * Examples:
+   * - `TokenName` → `TokenName:requestId=req-123`
+   * - `TokenName:abc123` → `TokenName:requestId=req-123:abc123`
+   *
+   * @param existingName The existing instance name (without requestId)
+   * @param requestId The request ID to add
+   * @returns The upgraded instance name with requestId
+   */
+  upgradeInstanceNameToRequest(existingName: string, requestId: string): string;
+  /**
+   * Formats a single argument value for instance name generation.
+   */
+  formatArgValue(value: any): string;
+}
+//#endregion
 //#region src/errors/di-error.d.mts
 declare enum DIErrorCode {
   FactoryNotFound = "FactoryNotFound",
@@ -240,6 +339,14 @@ declare enum DIErrorCode {
   InstanceNotFound = "InstanceNotFound",
   InstanceDestroying = "InstanceDestroying",
   CircularDependency = "CircularDependency",
+  TokenValidationError = "TokenValidationError",
+  TokenSchemaRequiredError = "TokenSchemaRequiredError",
+  ClassNotInjectable = "ClassNotInjectable",
+  ScopeMismatchError = "ScopeMismatchError",
+  PriorityConflictError = "PriorityConflictError",
+  StorageError = "StorageError",
+  InitializationError = "InitializationError",
+  DependencyResolutionError = "DependencyResolutionError",
   UnknownError = "UnknownError",
 }
 declare class DIError extends Error {
@@ -253,6 +360,14 @@ declare class DIError extends Error {
   static instanceDestroying(name: string): DIError;
   static unknown(message: string | Error, context?: Record<string, unknown>): DIError;
   static circularDependency(cycle: string[]): DIError;
+  static tokenValidationError(message: string, schema: InjectionTokenSchemaType | undefined, value: unknown): DIError;
+  static tokenSchemaRequiredError(token: string | symbol | unknown): DIError;
+  static classNotInjectable(className: string): DIError;
+  static scopeMismatchError(token: string | symbol | unknown, expectedScope: string, actualScope: string): DIError;
+  static priorityConflictError(token: string | symbol | unknown, records: FactoryRecord[]): DIError;
+  static storageError(message: string, operation: string, instanceName?: string): DIError;
+  static initializationError(serviceName: string, error: Error | string): DIError;
+  static dependencyResolutionError(serviceName: string, dependencyName: string, error: Error | string): DIError;
 }
 //#endregion
 //#region src/internal/holder/instance-holder.d.mts
@@ -269,8 +384,6 @@ declare enum InstanceStatus {
   /** Instance creation failed with an error */
   Error = "error",
 }
-/** Callback function for instance effects */
-type InstanceEffect = () => void;
 /** Callback function for instance destruction listeners */
 type InstanceDestroyListener = () => void | Promise<void>;
 /**
@@ -365,8 +478,7 @@ type HolderGetResult<T = unknown> = [undefined, InstanceHolder<T>] | [DIError, I
  * Interface for abstracting holder storage operations.
  *
  * Enables unified instance resolution logic regardless of where
- * holders are stored (singleton manager, request context, etc.).
- * This is the key abstraction for the Storage Strategy pattern.
+ * holders are stored. This is the key abstraction for the unified storage pattern.
  */
 interface IHolderStorage {
   /**
@@ -435,271 +547,296 @@ interface IHolderStorage {
    * @returns Array of instance names that have this instance as a dependency
    */
   findDependents(instanceName: string): string[];
+  /**
+   * Updates dependency references when instance names change.
+   * Used during scope upgrades when instance names are regenerated with requestId.
+   *
+   * @param oldName The old instance name
+   * @param newName The new instance name
+   */
+  updateDependencyReference(oldName: string, newName: string): void;
 }
 //#endregion
-//#region src/internal/holder/base-holder-manager.d.mts
+//#region src/internal/lifecycle/lifecycle-event-bus.d.mts
 /**
- * Result type for waitForHolderReady.
- * Returns either [undefined, holder] on success or [error] on failure.
+ * Event bus for service lifecycle events (create, destroy, etc.).
+ *
+ * Enables loose coupling between services by allowing them to subscribe
+ * to lifecycle events of their dependencies without direct references.
+ * Used primarily for invalidation cascading.
  */
-type HolderReadyResult<T> = [undefined, InstanceHolder<T>] | [DIError];
+declare class LifecycleEventBus {
+  private readonly logger;
+  private listeners;
+  constructor(logger?: Console | null);
+  on<Event extends string | `pre:${string}` | `post:${string}`>(ns: string, event: Event, listener: (event: Event) => void): () => void;
+  emit(key: string, event: string): Promise<PromiseSettledResult<any>[] | undefined>;
+}
+//#endregion
+//#region src/internal/core/service-invalidator.d.mts
+interface ClearAllOptions {
+  /** Whether to wait for all services to settle before starting (default: true) */
+  waitForSettlement?: boolean;
+}
+interface InvalidationOptions {
+  /** Whether to emit events after invalidation (default: true) */
+  emitEvents?: boolean;
+  /** Custom event emitter function */
+  onInvalidated?: (instanceName: string) => Promise<void>;
+  /** Whether to cascade invalidation to dependents (default: false - events handle it) */
+  cascade?: boolean;
+}
 /**
- * Abstract base class providing common functionality for managing InstanceHolder objects.
+ * Manages graceful service cleanup with event-based invalidation.
  *
- * Provides shared patterns for holder storage, creation, and lifecycle management
- * used by both singleton (HolderManager) and request-scoped (RequestContext) managers.
+ * Uses event subscriptions instead of manual dependent finding.
+ * When a service is created, it subscribes to destroy events of its dependencies.
+ * When a dependency is destroyed, the event automatically invalidates dependents.
  */
-declare abstract class BaseHolderManager {
-  protected readonly logger: Console | null;
-  protected readonly _holders: Map<string, InstanceHolder>;
+declare class ServiceInvalidator {
+  private readonly eventBus;
+  private readonly logger;
+  constructor(eventBus: LifecycleEventBus | null, logger?: Console | null);
   /**
-   * Reverse dependency index: maps a dependency name to the set of holder names that depend on it.
-   * This allows O(1) lookup of dependents instead of O(n) iteration.
+   * Invalidates a service using a specific storage.
+   * Event-based invalidation means dependents are automatically invalidated
+   * via destroy event subscriptions - no need to manually find dependents.
+   *
+   * @param service The instance name to invalidate
+   * @param storage The storage to use for this invalidation
+   * @param options Additional options for invalidation behavior
    */
-  protected readonly _dependents: Map<string, Set<string>>;
-  constructor(logger?: Console | null);
+  invalidateWithStorage(service: string, storage: IHolderStorage, options?: InvalidationOptions): Promise<void>;
   /**
-   * Protected getter for accessing the holders map from subclasses.
+   * Sets up destroy event subscriptions for a service's dependencies.
+   * Called when a service is successfully instantiated.
+   *
+   * @param serviceName The name of the service
+   * @param dependencies The set of dependency names
+   * @param storage The storage to use for invalidation
+   * @param holder The holder for the service (to add unsubscribe to destroy listeners)
    */
-  protected get holders(): Map<string, InstanceHolder>;
+  setupDependencySubscriptions(serviceName: string, dependencies: Set<string>, storage: IHolderStorage, holder: InstanceHolder): void;
   /**
-   * Abstract method to get a holder by name. Each implementation defines its own return type
-   * based on their specific error handling and validation needs.
+   * Gracefully clears all services in a specific storage.
+   * This allows clearing request-scoped services using a RequestStorage.
    */
-  abstract get(name: string): any;
+  clearAllWithStorage(storage: IHolderStorage, options?: ClearAllOptions): Promise<void>;
   /**
-   * Abstract method to set a holder by name. Each implementation may have different validation logic.
+   * Waits for all services in a specific storage to settle.
    */
-  abstract set(name: string, holder: InstanceHolder): void;
+  readyWithStorage(storage: IHolderStorage): Promise<void>;
   /**
-   * Abstract method to check if a holder exists. Each implementation may have different validation logic.
+   * Invalidates a single holder using a specific storage.
    */
-  abstract has(name: string): any;
+  private invalidateHolderWithStorage;
   /**
-   * Deletes a holder by name and cleans up the reverse dependency index.
-   * @param name The name of the holder to delete
-   * @returns true if the holder was deleted, false if it didn't exist
+   * Common invalidation logic for holders based on their status.
    */
-  delete(name: string): boolean;
+  private invalidateHolderByStatus;
   /**
-   * Registers a holder's dependencies in the reverse index.
-   * Call this after creating a holder with dependencies.
-   * @param holderName The name of the holder that has dependencies
-   * @param deps The set of dependency names
+   * Destroys a holder using a specific storage.
    */
-  registerDependencies(holderName: string, deps: Set<string>): void;
+  private destroyHolderWithStorage;
   /**
-   * Removes a holder from the reverse dependency index.
-   * @param holderName The name of the holder to remove
-   * @param deps The set of dependency names to clean up
+   * Waits for a holder to settle (either created, destroyed, or error state).
    */
-  protected removeFromDependentsIndex(holderName: string, deps: Set<string>): void;
+  private waitForHolderToSettle;
   /**
-   * Gets all holder names that depend on the given instance name.
-   * O(1) lookup using the reverse dependency index.
-   * @param instanceName The instance name to find dependents for
-   * @returns Array of holder names that depend on this instance
+   * Emits events to listeners for instance lifecycle events.
    */
-  getDependents(instanceName: string): string[];
-  /**
-   * Filters holders based on a predicate function.
-   * @param predicate Function to test each holder
-   * @returns A new Map containing only the holders that match the predicate
-   * @deprecated Use forEachHolder() for iteration to avoid allocations
-   */
-  filter(predicate: (value: InstanceHolder<any>, key: string) => boolean): Map<string, InstanceHolder>;
-  /**
-   * Iterates over holders with a callback. More efficient than filter() as it
-   * avoids creating intermediate arrays and Maps.
-   * @param callback Function called for each holder with (holder, name)
-   */
-  forEachHolder(callback: (holder: InstanceHolder<any>, name: string) => void): void;
-  /**
-   * Finds the first holder matching a predicate. More efficient than filter()
-   * when only one result is needed.
-   * @param predicate Function to test each holder
-   * @returns The first matching holder or undefined
-   */
-  findHolder(predicate: (holder: InstanceHolder<any>, name: string) => boolean): InstanceHolder | undefined;
-  /**
-   * Clears all holders from this manager and the reverse dependency index.
-   */
-  clear(): void;
-  /**
-   * Gets the number of holders currently managed.
-   */
-  size(): number;
-  /**
-   * Creates a new holder with Creating status and a deferred creation promise.
-   * This is useful for creating placeholder holders that can be fulfilled later.
-   * @param name The name of the instance
-   * @param type The injectable type
-   * @param scope The injectable scope
-   * @param deps Optional set of dependencies
-   * @returns A tuple containing the deferred promise and the holder
-   */
-  createCreatingHolder<Instance>(name: string, type: InjectableType, scope: InjectableScope, deps?: Set<string>): [ReturnType<typeof Promise.withResolvers<[undefined, Instance]>>, InstanceHolder<Instance>];
-  /**
-   * Creates a new holder with Created status and an actual instance.
-   * This is useful for creating holders that already have their instance ready.
-   * @param name The name of the instance
-   * @param instance The actual instance to store
-   * @param type The injectable type
-   * @param scope The injectable scope
-   * @param deps Optional set of dependencies
-   * @returns The created holder
-   */
-  protected createCreatedHolder<Instance>(name: string, instance: Instance, type: InjectableType, scope: InjectableScope, deps?: Set<string>): InstanceHolder<Instance>;
+  private emitInstanceEvent;
+}
+//#endregion
+//#region src/internal/core/token-resolver.d.mts
+/**
+ * Handles token validation and resolution.
+ *
+ * Focuses on token validation, normalization, and argument validation.
+ * Name generation is handled by NameResolver.
+ */
+declare class TokenResolver {
+  private readonly logger;
+  constructor(logger?: Console | null);
   /**
-   * Gets all holder names currently managed.
+   * Normalizes a token to an InjectionToken.
+   * Handles class constructors by getting their injectable token.
+   *
+   * @param token A class constructor, InjectionToken, BoundInjectionToken, or FactoryInjectionToken
+   * @returns The normalized InjectionTokenType
    */
-  getAllNames(): string[];
+  normalizeToken(token: AnyInjectableType): InjectionTokenType;
   /**
-   * Gets all holders currently managed.
+   * Gets the underlying "real" token from wrapped tokens.
+   * For BoundInjectionToken and FactoryInjectionToken, returns the wrapped token.
+   * For other tokens, returns the token itself.
+   *
+   * @param token The token to unwrap
+   * @returns The underlying InjectionToken
    */
-  getAllHolders(): InstanceHolder[];
+  getRealToken<T = unknown>(token: InjectionTokenType): InjectionToken<T>;
   /**
-   * Checks if this manager has any holders.
+   * Convenience method that normalizes a token and then gets the real token.
+   * Useful for checking registry entries where you need the actual registered token.
+   *
+   * @param token Any injectable type
+   * @returns The underlying InjectionToken
    */
-  isEmpty(): boolean;
+  getRegistryToken<T = unknown>(token: AnyInjectableType): InjectionToken<T>;
   /**
-   * Waits for a holder to be ready and returns the appropriate result.
-   * This is a shared utility used by both singleton and request-scoped resolution.
+   * Validates and resolves token arguments, handling factory token resolution and validation.
    *
-   * @param holder The holder to wait for
-   * @param waiterHolder Optional holder that is doing the waiting (for circular dependency detection)
-   * @param getHolder Optional function to retrieve holders by name (required if waiterHolder is provided)
-   * @returns A promise that resolves with [undefined, holder] on success or [DIError] on failure
+   * @param token The token to validate
+   * @param args Optional arguments
+   * @returns [error, { actualToken, validatedArgs }]
    */
-  static waitForHolderReady<T>(holder: InstanceHolder<T>, waiterHolder?: InstanceHolder, getHolder?: (name: string) => InstanceHolder | undefined): Promise<HolderReadyResult<T>>;
+  validateAndResolveTokenArgs(token: AnyInjectableType, args?: any): [DIError | undefined, {
+    actualToken: InjectionTokenType;
+    validatedArgs?: any;
+  }];
 }
 //#endregion
-//#region src/internal/context/request-context.d.mts
+//#region src/internal/holder/unified-storage.d.mts
 /**
- * Interface for request context that manages pre-prepared instances for a specific request.
+ * Unified storage implementation that works the same way regardless of scope.
+ * Replaces RequestContext, HolderManager, SingletonStorage, RequestStorage.
  *
- * Provides isolated storage for request-scoped services, enabling efficient
- * instantiation and cleanup within the lifecycle of a single request.
+ * Scope is just metadata - storage operations are identical for all scopes.
+ * Different storage instances are just isolated storage spaces.
  */
-interface RequestContext {
-  /**
-   * Unique identifier for this request context.
-   */
-  readonly requestId: string;
+declare class UnifiedStorage implements IHolderStorage {
+  readonly scope: InjectableScope;
+  private readonly holders;
   /**
-   * Instance holders for request-scoped services.
+   * Reverse dependency index: maps a dependency name to the set of holder names that depend on it.
+   * This allows O(1) lookup of dependents instead of O(n) iteration.
    */
-  readonly holders: Map<string, InstanceHolder>;
+  private readonly dependents;
+  constructor(scope?: InjectableScope);
+  get<T = unknown>(instanceName: string): HolderGetResult<T>;
+  set(instanceName: string, holder: InstanceHolder): void;
+  delete(instanceName: string): boolean;
+  createHolder<T>(instanceName: string, type: InjectableType, deps: Set<string>): [ReturnType<typeof Promise.withResolvers<[undefined, T]>>, InstanceHolder<T>];
+  storeInstance(instanceName: string, instance: unknown): void;
+  handles(scope: InjectableScope): boolean;
+  getAllNames(): string[];
+  forEach(callback: (name: string, holder: InstanceHolder) => void): void;
+  findByInstance(instance: unknown): InstanceHolder | null;
+  findDependents(instanceName: string): string[];
   /**
-   * Priority for resolution in FactoryContext.inject method.
-   * Higher values take precedence.
+   * Updates dependency references when instance names change.
+   * Used during scope upgrades when instance names are regenerated with requestId.
+   *
+   * @param oldName The old instance name
+   * @param newName The new instance name
    */
-  readonly priority: number;
+  updateDependencyReference(oldName: string, newName: string): void;
   /**
-   * Request-specific metadata that can be used during instantiation.
+   * Registers a holder's dependencies in the reverse index.
    */
-  readonly metadata: Map<string, any>;
+  private registerDependencies;
   /**
-   * Timestamp when this context was created.
+   * Removes a holder from the reverse dependency index.
    */
-  readonly createdAt: number;
+  private removeFromDependentsIndex;
+}
+//#endregion
+//#region src/container/abstract-container.d.mts
+/**
+ * Abstract base class for dependency injection containers.
+ *
+ * Provides shared implementation for common container operations.
+ * Both Container and ScopedContainer extend this class.
+ */
+declare abstract class AbstractContainer implements IContainer {
   /**
-   * Adds a pre-prepared instance to this context.
+   * The default scope used when adding instances without explicit registration.
    */
-  addInstance(instanceName: string, instance: any, holder: InstanceHolder): void;
+  protected abstract readonly defaultScope: InjectableScope;
   /**
-   * Adds a pre-prepared instance to this context.
+   * The request ID for scoped containers, undefined for root container.
    */
-  addInstance(token: InjectionToken<any, undefined>, instance: any): void;
+  protected abstract readonly requestId: string | undefined;
   /**
-   * Gets an instance holder from this context.
+   * Gets the storage for this container.
    */
-  get(instanceName: string): InstanceHolder | undefined;
+  abstract getStorage(): UnifiedStorage;
   /**
-   * Sets an instance holder by name.
+   * Gets the registry for this container.
    */
-  set(instanceName: string, holder: InstanceHolder): void;
+  protected abstract getRegistry(): Registry;
   /**
-   * Checks if this context has a pre-prepared instance.
+   * Gets the token resolver.
    */
-  has(instanceName: string): boolean;
+  protected abstract getTokenResolver(): TokenResolver;
   /**
-   * Clears all instances and holders from this context.
+   * Gets the name resolver.
    */
-  clear(): void;
+  protected abstract getNameResolver(): NameResolver;
   /**
-   * Gets metadata value by key.
+   * Gets the service invalidator.
    */
-  getMetadata(key: string): any | undefined;
+  protected abstract getServiceInvalidator(): ServiceInvalidator;
   /**
-   * Sets metadata value by key.
-   */
-  setMetadata(key: string, value: any): void;
-  /**
-   * Filters holders based on a predicate function.
+   * Gets an instance from the container.
    */
-  filter(predicate: (value: InstanceHolder<any>, key: string) => boolean): Map<string, InstanceHolder>;
+  abstract get<T extends ClassType>(token: T): InstanceType<T> extends Factorable<infer R> ? Promise<R> : Promise<InstanceType<T>>;
+  abstract get<T extends ClassTypeWithArgument<R>, R>(token: T, args: R): Promise<InstanceType<T>>;
+  abstract get<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, args: z.input<S>): Promise<T>;
+  abstract get<T, S extends InjectionTokenSchemaType, R extends boolean>(token: InjectionToken<T, S, R>): R extends false ? Promise<T> : S extends ZodType<infer Type> ? `Error: Your token requires args: ${Join<UnionToArray<keyof Type>, ', '>}` : 'Error: Your token requires args';
+  abstract get<T>(token: InjectionToken<T, undefined>): Promise<T>;
+  abstract get<T>(token: BoundInjectionToken<T, any>): Promise<T>;
+  abstract get<T>(token: FactoryInjectionToken<T, any>): Promise<T>;
   /**
-   * Deletes a holder by name.
+   * Invalidates a service and its dependencies.
    */
-  delete(name: string): boolean;
+  abstract invalidate(service: unknown): Promise<void>;
   /**
-   * Gets the number of holders currently managed.
+   * Disposes the container and cleans up all resources.
    */
-  size(): number;
+  abstract dispose(): Promise<void>;
   /**
-   * Checks if this manager has any holders.
+   * Calculates the instance name for a given token and optional arguments.
+   *
+   * @internal
+   * @param token The class type, InjectionToken, BoundInjectionToken, or FactoryInjectionToken
+   * @param args Optional arguments (ignored for BoundInjectionToken which uses its bound value)
+   * @returns The calculated instance name string, or null if the token is a FactoryInjectionToken that is not yet resolved
    */
-  isEmpty(): boolean;
+  calculateInstanceName(token: ClassType | InjectionToken<any, any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any>, args?: unknown): string | null;
   /**
-   * Registers a holder's dependencies in the reverse index.
+   * Checks if a service is registered in the container.
    */
-  registerDependencies(holderName: string, deps: Set<string>): void;
+  isRegistered(token: any): boolean;
   /**
-   * Gets all holder names that depend on the given instance name.
-   * O(1) lookup using the reverse dependency index.
+   * Waits for all pending operations to complete.
    */
-  getDependents(instanceName: string): string[];
-}
-/** @deprecated Use RequestContext instead */
-type RequestContextHolder = RequestContext;
-/**
- * Default implementation of RequestContext.
- *
- * Extends BaseHolderManager to provide holder management functionality
- * with request-specific metadata and lifecycle support.
- */
-declare class DefaultRequestContext extends BaseHolderManager implements RequestContext {
-  readonly requestId: string;
-  readonly priority: number;
-  readonly metadata: Map<string, any>;
-  readonly createdAt: number;
-  constructor(requestId: string, priority?: number, initialMetadata?: Record<string, any>);
+  ready(): Promise<void>;
   /**
-   * Public getter for holders to maintain interface compatibility.
+   * @internal
+   * Attempts to get an instance synchronously if it already exists.
    */
-  get holders(): Map<string, InstanceHolder>;
+  tryGetSync<T>(token: any, args?: any): T | null;
   /**
-   * Gets a holder by name. For RequestContext, this is a simple lookup.
+   * @internal
+   * Internal method for getting instances synchronously with configurable storage.
    */
-  get(name: string): InstanceHolder | undefined;
+  protected tryGetSyncFromStorage<T>(token: any, args: any, storage: UnifiedStorage, requestId?: string): T | null;
   /**
-   * Sets a holder by name.
+   * Adds an instance to the container.
+   * Accepts class types, InjectionTokens, and BoundInjectionTokens.
+   * Rejects InjectionTokens with required schemas (use BoundInjectionToken instead).
+   *
+   * @param token The class type, InjectionToken, or BoundInjectionToken to register the instance for
+   * @param instance The instance to store
    */
-  set(name: string, holder: InstanceHolder): void;
+  addInstance<T>(token: ClassType | InjectionToken<T, any> | BoundInjectionToken<T, any>, instance: T): void;
   /**
-   * Checks if a holder exists by name.
+   * @internal
+   * Internal method for adding instances with configurable scope and storage.
    */
-  has(name: string): boolean;
-  addInstance(instanceName: string | InjectionToken<any, undefined>, instance: any, holder?: InstanceHolder): void;
-  clear(): void;
-  getMetadata(key: string): any | undefined;
-  setMetadata(key: string, value: any): void;
+  protected addInstanceToStorage<T>(token: ClassType | InjectionToken<T, any> | BoundInjectionToken<T, any>, instance: T, storage: UnifiedStorage, scope: InjectableScope, requestId?: string): void;
 }
-/**
- * Creates a new request context with the given parameters.
- */
-declare function createRequestContext(requestId: string, priority?: number, initialMetadata?: Record<string, any>): RequestContext;
 //#endregion
 //#region src/container/scoped-container.d.mts
 /**
@@ -710,23 +847,20 @@ declare function createRequestContext(requestId: string, priority?: number, init
  * This design eliminates race conditions that can occur with async operations
  * when multiple requests are processed concurrently.
  */
-declare class ScopedContainer implements IContainer {
+declare class ScopedContainer extends AbstractContainer {
   private readonly parent;
   private readonly registry;
   readonly requestId: string;
-  private readonly requestContextHolder;
-  private readonly holderStorage;
+  protected readonly defaultScope = InjectableScope.Request;
+  private readonly storage;
   private disposed;
-  constructor(parent: Container, registry: Registry, requestId: string, metadata?: Record<string, any>, priority?: number);
-  /**
-   * Gets the request context holder for this scoped container.
-   */
-  getRequestContextHolder(): RequestContext;
-  /**
-   * Gets the holder storage for this scoped container.
-   * Used by InstanceResolver for request-scoped resolution.
-   */
-  getHolderStorage(): IHolderStorage;
+  private readonly metadata;
+  constructor(parent: Container, registry: Registry, requestId: string, metadata?: Record<string, any>);
+  getStorage(): UnifiedStorage;
+  protected getRegistry(): Registry;
+  protected getTokenResolver(): TokenResolver;
+  protected getNameResolver(): NameResolver;
+  protected getServiceInvalidator(): ServiceInvalidator;
   /**
    * Gets the request ID for this scoped container.
    */
@@ -743,13 +877,9 @@ declare class ScopedContainer implements IContainer {
    * Sets metadata on the request context.
    */
   setMetadata(key: string, value: any): void;
-  /**
-   * Adds a pre-prepared instance to the request context.
-   */
-  addInstance(token: InjectionToken<any, undefined>, instance: any): void;
   /**
    * Gets an instance from the container.
-   * Request-scoped services are resolved from this container's context.
+   * Request-scoped services are resolved from this container's storage.
    * All other services are delegated to the parent container.
    */
   get<T extends ClassType>(token: T): InstanceType<T> extends Factorable<infer R> ? Promise<R> : Promise<InstanceType<T>>;
@@ -761,354 +891,251 @@ declare class ScopedContainer implements IContainer {
   get<T>(token: FactoryInjectionToken<T, any>): Promise<T>;
   /**
    * Invalidates a service and its dependencies.
-   * For request-scoped services, invalidation is handled within this context.
    */
   invalidate(service: unknown): Promise<void>;
   /**
-   * Checks if a service is registered.
-   */
-  isRegistered(token: any): boolean;
-  /**
-   * Disposes this scoped container and cleans up all request-scoped instances.
-   * This is an alias for endRequest() for IContainer compatibility.
+   * Disposes the container and cleans up all resources.
+   * Alias for endRequest().
    */
   dispose(): Promise<void>;
-  /**
-   * Ends the request and cleans up all request-scoped instances.
-   * Uses the invalidation system to properly cascade to dependent singletons.
-   */
-  endRequest(): Promise<void>;
-  /**
-   * Waits for all pending operations to complete.
-   */
-  ready(): Promise<void>;
   /**
    * @internal
-   * Attempts to get an instance synchronously if it already exists and is ready.
-   * For request-scoped services, checks this container's context first.
-   * For other services, delegates to the parent container.
-   *
-   * Returns null if the instance doesn't exist or is not yet ready (still creating).
+   * Attempts to get an instance synchronously if it already exists.
+   * Checks request storage first, then delegates to parent.
    */
   tryGetSync<T>(token: any, args?: any): T | null;
   /**
-   * Checks if a token is for a request-scoped service.
-   */
-  private isRequestScoped;
-  /**
-   * Resolves a request-scoped service from this container's context.
-   * Uses locking to prevent duplicate initialization during concurrent resolution.
-   */
-  private resolveRequestScoped;
-  /**
-   * Stores an instance in the request context.
-   * Called by Container during request-scoped service resolution.
-   */
-  storeRequestInstance(instanceName: string, instance: any, holder: InstanceHolder): void;
-  /**
-   * Gets an existing instance from the request context.
-   * Called by Container during resolution to check for existing instances.
+   * Adds an instance to the container.
+   * Overrides base class to check disposed state.
    */
-  getRequestInstance(instanceName: string): InstanceHolder | undefined;
+  addInstance<T>(token: ClassType | InjectionToken<T, any> | BoundInjectionToken<T, any>, instance: T): void;
   /**
-   * Generates a prefixed event name for request-scoped services.
-   * Format: {requestId}:{instanceName}
+   * Ends the request and cleans up all request-scoped services.
    */
-  getPrefixedEventName(instanceName: string): string;
-}
-//#endregion
-//#region src/internal/lifecycle/lifecycle-event-bus.d.mts
-/**
- * Event bus for service lifecycle events (create, destroy, etc.).
- *
- * Enables loose coupling between services by allowing them to subscribe
- * to lifecycle events of their dependencies without direct references.
- * Used primarily for invalidation cascading.
- */
-declare class LifecycleEventBus {
-  private readonly logger;
-  private listeners;
-  constructor(logger?: Console | null);
-  on<Event extends string | `pre:${string}` | `post:${string}`>(ns: string, event: Event, listener: (event: Event) => void): () => void;
-  emit(key: string, event: string): Promise<PromiseSettledResult<any>[] | undefined>;
+  endRequest(): Promise<void>;
 }
 //#endregion
-//#region src/internal/holder/holder-manager.d.mts
+//#region src/internal/core/scope-tracker.d.mts
 /**
- * Manages the storage and retrieval of singleton instance holders.
+ * Component for tracking and handling scope upgrades.
  *
- * Provides CRUD operations and filtering for the holder map.
- * Handles holder state validation (destroying, error states) on retrieval.
+ * Detects when a Singleton service needs to be upgraded to Request scope
+ * and coordinates the scope upgrade process atomically.
  */
-declare class HolderManager extends BaseHolderManager {
-  constructor(logger?: Console | null);
-  get(name: string): [DIError, InstanceHolder] | [DIError] | [undefined, InstanceHolder];
-  set(name: string, holder: InstanceHolder): void;
-  has(name: string): [DIError] | [undefined, boolean];
-  /**
-   * Creates a new holder with Created status and stores it.
-   * This is useful for creating holders that already have their instance ready.
-   * @param name The name of the instance
-   * @param instance The actual instance to store
-   * @param type The injectable type
-   * @param scope The injectable scope
-   * @param deps Optional set of dependencies
-   * @returns The created holder
-   */
-  storeCreatedHolder<Instance>(name: string, instance: Instance, type: InjectableType, scope: InjectableScope, deps?: Set<string>): InstanceHolder<Instance>;
-}
-//#endregion
-//#region src/internal/core/invalidator.d.mts
-interface ClearAllOptions {
-  /** Maximum number of invalidation rounds to prevent infinite loops (default: 10) */
-  maxRounds?: number;
-  /** Whether to wait for all services to settle before starting (default: true) */
-  waitForSettlement?: boolean;
-}
-interface InvalidationOptions {
-  /** Whether to emit events after invalidation (default: true for singletons) */
-  emitEvents?: boolean;
-  /** Custom event emitter function */
-  onInvalidated?: (instanceName: string) => Promise<void>;
-  /** Whether to cascade invalidation to dependents (default: true) */
-  cascade?: boolean;
-  /** Internal: tracks services being invalidated in the current call chain to prevent circular loops */
-  _invalidating?: Set<string>;
-}
-/**
- * Manages graceful service cleanup with dependency-aware invalidation.
- *
- * Ensures services are destroyed in the correct order based on their dependencies.
- * Works with any IHolderStorage implementation, enabling unified invalidation
- * for both singleton and request-scoped services.
- */
-declare class Invalidator {
-  private readonly eventBus;
+declare class ScopeTracker {
+  private readonly registry;
+  private readonly nameResolver;
   private readonly logger;
-  private readonly storage;
-  constructor(manager: HolderManager, eventBus: LifecycleEventBus | null, logger?: Console | null);
+  constructor(registry: Registry, nameResolver: NameResolver, logger?: Console | null);
   /**
-   * Invalidates a service and all its dependencies.
-   * Works with the configured storage (singleton by default).
-   */
-  invalidate(service: string, round?: number): Promise<any>;
-  /**
-   * Invalidates a service using a specific storage.
-   * This allows request-scoped invalidation using a RequestStorage.
+   * Checks if a dependency requires scope upgrade and performs it if needed.
+   * Called during service resolution when a dependency is resolved.
    *
-   * @param service The instance name to invalidate
-   * @param storage The storage to use for this invalidation
-   * @param round Current invalidation round (for recursion limiting)
-   * @param options Additional options for invalidation behavior
-   */
-  invalidateWithStorage(service: string, storage: IHolderStorage, round?: number, options?: InvalidationOptions): Promise<void>;
-  /**
-   * Gracefully clears all services using invalidation logic.
-   * This method respects service dependencies and ensures proper cleanup order.
-   * Services that depend on others will be invalidated first, then their dependencies.
-   */
-  clearAll(options?: ClearAllOptions): Promise<void>;
-  /**
-   * Gracefully clears all services in a specific storage.
-   * This allows clearing request-scoped services using a RequestStorage.
-   */
-  clearAllWithStorage(storage: IHolderStorage, options?: ClearAllOptions): Promise<void>;
-  /**
-   * Waits for all services to settle (either created, destroyed, or error state).
-   */
-  ready(): Promise<void>;
-  /**
-   * Waits for all services in a specific storage to settle.
-   */
-  readyWithStorage(storage: IHolderStorage): Promise<void>;
-  /**
-   * Invalidates a single holder using a specific storage.
-   */
-  private invalidateHolderWithStorage;
-  /**
-   * Common invalidation logic for holders based on their status.
-   */
-  private invalidateHolderByStatus;
-  /**
-   * Destroys a holder using a specific storage.
+   * @param currentServiceName - Name of the service being created
+   * @param currentServiceScope - Current scope of the service being created
+   * @param dependencyName - Name of the dependency being resolved
+   * @param dependencyScope - Scope of the dependency
+   * @param dependencyToken - Token of the dependency
+   * @param singletonStorage - Singleton storage instance
+   * @param requestStorage - Request storage instance (if in request context)
+   * @param requestId - Request ID (if in request context)
+   * @returns [needsUpgrade: boolean, newName?: string] - whether upgrade occurred and new name
+   */
+  checkAndUpgradeScope(currentServiceName: string, currentServiceScope: InjectableScope, dependencyName: string, dependencyScope: InjectableScope, dependencyToken: InjectionToken<any, any>, singletonStorage: IHolderStorage, requestStorage?: IHolderStorage, requestId?: string): [boolean, string?];
+  /**
+   * Performs the actual scope upgrade from Singleton to Request.
+   * This is the core migration logic.
+   *
+   * @param serviceName - Current service name (without requestId)
+   * @param token - Service injection token
+   * @param singletonStorage - Source storage
+   * @param requestStorage - Target storage
+   * @param requestId - Request ID to include in new name
+   * @returns [success: boolean, newName?: string, error?: DIError]
    */
-  private destroyHolderWithStorage;
+  upgradeScopeToRequest(serviceName: string, token: InjectionToken<any, any>, singletonStorage: IHolderStorage, requestStorage: IHolderStorage, requestId: string): Promise<[boolean, string?, DIError?]>;
   /**
-   * Waits for a holder to settle (either created, destroyed, or error state).
+   * Synchronous part of scope upgrade - handles immediate updates.
+   * Async operations (like waiting for holder creation) should be done separately.
    */
-  private waitForHolderToSettle;
+  private upgradeScopeToRequestSync;
   /**
-   * Clears services with dependency awareness for a specific storage.
+   * Updates all parent dependencies to reference the new service name.
+   *
+   * @param oldName - Original service name
+   * @param newName - New service name with requestId
+   * @param singletonStorage - Singleton storage to check
+   * @param requestStorage - Request storage to check
    */
-  private clearServicesWithDependencyAwarenessForStorage;
+  updateParentDependencies(oldName: string, newName: string, singletonStorage: IHolderStorage, requestStorage?: IHolderStorage): void;
+}
+//#endregion
+//#region src/internal/core/service-initializer.d.mts
+/**
+ * Creates service instances from registry records.
+ *
+ * Handles both class-based (@Injectable) and factory-based (@Factory) services,
+ * managing the instantiation lifecycle including lifecycle hook invocation.
+ */
+declare class ServiceInitializer {
+  private readonly injectors;
+  constructor(injectors: Injectors);
   /**
-   * Finds services that are ready to be cleared in the current round.
-   * A service is ready if all its dependencies have already been cleared.
+   * Instantiates a service based on its registry record.
+   * @param ctx The factory context for dependency injection
+   * @param record The factory record from the registry
+   * @param args Optional arguments for the service
+   * @returns Promise resolving to [undefined, instance] or [error]
    */
-  private findServicesReadyForClearingInStorage;
+  instantiateService<T>(ctx: ServiceInitializationContext, record: FactoryRecord<T, any>, args?: any): Promise<[undefined, T] | [DIError]>;
   /**
-   * Force clears services that couldn't be cleared through normal dependency resolution.
-   * This handles edge cases like circular dependencies.
+   * Instantiates a class-based service (Injectable decorator).
+   * @param ctx The factory context for dependency injection
+   * @param record The factory record from the registry
+   * @param args Optional arguments for the service constructor
+   * @returns Promise resolving to [undefined, instance] or [error]
    */
-  private forceClearServicesInStorage;
+  private instantiateClass;
   /**
-   * Emits events to listeners for instance lifecycle events.
+   * Instantiates a factory-based service (Factory decorator).
+   * @param ctx The factory context for dependency injection
+   * @param record The factory record from the registry
+   * @param args Optional arguments for the factory
+   * @returns Promise resolving to [undefined, instance] or [error]
    */
-  private emitInstanceEvent;
+  private instantiateFactory;
 }
 //#endregion
-//#region src/internal/core/token-processor.d.mts
+//#region src/internal/core/instance-resolver.d.mts
 /**
- * Handles token validation, normalization, and instance name generation.
+ * Resolves instances from tokens, handling caching, creation, and scope rules.
  *
- * Provides utilities for resolving tokens to their underlying InjectionToken,
- * validating arguments against schemas, and generating unique instance identifiers.
+ * Uses unified storage for both singleton and request-scoped services.
+ * Coordinates with ServiceInitializer for actual service creation.
+ * Integrates ScopeTracker for automatic scope upgrades.
  */
-declare class TokenProcessor {
+declare class InstanceResolver {
+  private readonly registry;
+  private readonly storage;
+  private readonly serviceInitializer;
+  private readonly tokenResolver;
+  private readonly nameResolver;
+  private readonly scopeTracker;
+  private readonly serviceInvalidator;
+  private readonly eventBus;
   private readonly logger;
-  private readonly instanceNameCache;
-  constructor(logger?: Console | null);
+  constructor(registry: Registry, storage: IHolderStorage, serviceInitializer: ServiceInitializer, tokenResolver: TokenResolver, nameResolver: NameResolver, scopeTracker: ScopeTracker, serviceInvalidator: ServiceInvalidator, eventBus: LifecycleEventBus, logger?: Console | null);
   /**
-   * Normalizes a token to an InjectionToken.
-   * Handles class constructors by getting their injectable token.
+   * Resolves an instance for the given token and arguments.
+   * This method is used for singleton and transient services.
    *
-   * @param token A class constructor, InjectionToken, BoundInjectionToken, or FactoryInjectionToken
-   * @returns The normalized InjectionTokenType
+   * @param token The injection token
+   * @param args Optional arguments
+   * @param contextContainer The container to use for creating context
+   * @param requestStorage Optional request storage (for scope upgrades)
+   * @param requestId Optional request ID (for scope upgrades)
    */
-  normalizeToken(token: AnyInjectableType): InjectionTokenType;
+  resolveInstance(token: AnyInjectableType, args: any, contextContainer: IContainer, requestStorage?: IHolderStorage, requestId?: string): Promise<[undefined, any] | [DIError]>;
   /**
-   * Gets the underlying "real" token from wrapped tokens.
-   * For BoundInjectionToken and FactoryInjectionToken, returns the wrapped token.
-   * For other tokens, returns the token itself.
+   * Resolves a request-scoped instance for a ScopedContainer.
+   * The service will be stored in the ScopedContainer's request storage.
    *
-   * @param token The token to unwrap
-   * @returns The underlying InjectionToken
+   * @param token The injection token
+   * @param args Optional arguments
+   * @param scopedContainer The ScopedContainer that owns the request context
    */
-  getRealToken<T = unknown>(token: InjectionTokenType): InjectionToken<T>;
+  resolveRequestScopedInstance(token: AnyInjectableType, args: any, scopedContainer: ScopedContainer): Promise<[undefined, any] | [DIError]>;
   /**
-   * Convenience method that normalizes a token and then gets the real token.
-   * Useful for checking registry entries where you need the actual registered token.
+   * Unified resolution method that works with any IHolderStorage.
+   * This eliminates duplication between singleton and request-scoped resolution.
    *
-   * @param token Any injectable type
-   * @returns The underlying InjectionToken
+   * IMPORTANT: The check-and-store logic is carefully designed to avoid race conditions.
+   * The storage check and holder creation must happen synchronously (no awaits between).
+   *
+   * @param token The injection token
+   * @param args Optional arguments
+   * @param contextContainer The container for context
+   * @param storage The storage strategy to use
+   * @param scopedContainer Optional scoped container for request-scoped services
+   * @param requestStorage Optional request storage (for scope upgrades)
+   * @param requestId Optional request ID (for scope upgrades)
    */
-  getRegistryToken<T = unknown>(token: AnyInjectableType): InjectionToken<T>;
+  private resolveWithStorage;
   /**
-   * Validates and resolves token arguments, handling factory token resolution and validation.
+   * Internal method to resolve token args and create instance name.
+   * Handles factory token resolution and validation.
    */
-  validateAndResolveTokenArgs(token: AnyInjectableType, args?: any): [DIError | undefined, {
-    actualToken: InjectionTokenType;
-    validatedArgs?: any;
-  }];
+  private resolveTokenAndPrepareInstanceName;
   /**
-   * Generates a unique instance name based on token and arguments.
-   * Results are cached using an LRU cache for performance.
+   * Handles storage error states (destroying, error, etc.).
+   * Returns a result if handled, null if should proceed with creation.
    */
-  generateInstanceName(token: InjectionTokenType, args: any): string;
+  private handleStorageError;
   /**
-   * Formats a single argument value for instance name generation.
+   * Creates a new instance and stores it using the provided storage strategy.
+   * This unified method replaces instantiateServiceFromRegistry and createRequestScopedInstance.
+   *
+   * For transient services, the instance is created but not stored (no caching).
    */
-  formatArgValue(value: any): string;
+  private createAndStoreInstance;
   /**
-   * Creates a factory context for dependency injection during service instantiation.
-   * @param container The container instance (Container or ScopedContainer) for dependency resolution
-   * @param onDependencyResolved Callback when a dependency is resolved, receives the instance name
+   * Creates a transient instance without storage or locking.
+   * Each call creates a new instance.
    */
-  createFactoryContext(container: IContainer, onDependencyResolved?: (instanceName: string) => void): FactoryContext & {
-    getDestroyListeners: () => (() => void)[];
-    deps: Set<string>;
-  };
-}
-//#endregion
-//#region src/internal/core/service-locator.d.mts
-/**
- * Core DI engine that coordinates service instantiation, resolution, and lifecycle.
- *
- * Acts as the central orchestrator for dependency injection operations,
- * delegating to specialized components (InstanceResolver, Instantiator, Invalidator)
- * for specific tasks.
- */
-declare class ServiceLocator {
-  private readonly registry;
-  private readonly logger;
-  private readonly injectors;
-  private readonly eventBus;
-  private readonly manager;
-  private readonly instantiator;
-  private readonly tokenProcessor;
-  private readonly invalidator;
-  private readonly instanceResolver;
-  constructor(registry?: Registry, logger?: Console | null, injectors?: Injectors);
-  getEventBus(): LifecycleEventBus;
-  getManager(): HolderManager;
-  getInvalidator(): Invalidator;
-  getTokenProcessor(): TokenProcessor;
-  getInstanceIdentifier(token: AnyInjectableType, args?: any): string;
+  private createTransientInstance;
   /**
-   * Gets or creates an instance for the given token.
-   * @param token The injection token
-   * @param args Optional arguments
-   * @param contextContainer The container to use for creating FactoryContext
+   * Handles successful service instantiation.
    */
-  getInstance(token: AnyInjectableType, args: any, contextContainer: IContainer): Promise<any[]>;
+  private handleInstantiationSuccess;
   /**
-   * Gets or throws an instance for the given token.
-   * @param token The injection token
-   * @param args Optional arguments
-   * @param contextContainer The container to use for creating FactoryContext
+   * Handles service instantiation errors.
    */
-  getOrThrowInstance<Instance>(token: AnyInjectableType, args: any, contextContainer: IContainer): Promise<Instance>;
+  private handleInstantiationError;
   /**
-   * Resolves a request-scoped service for a ScopedContainer.
-   * The service will be stored in the ScopedContainer's request context.
-   *
-   * @param token The injection token
-   * @param args Optional arguments
-   * @param scopedContainer The ScopedContainer that owns the request context
+   * Handles instantiation result (success or error).
    */
-  resolveRequestScoped(token: AnyInjectableType, args: any, scopedContainer: ScopedContainer): Promise<any>;
-  getSyncInstance<Instance, Schema extends InjectionTokenSchemaType | undefined>(token: AnyInjectableType, args: Schema extends ZodObject ? z.input<Schema> : Schema extends ZodOptional<ZodObject> ? z.input<Schema> | undefined : undefined, contextContainer: IContainer): Instance | null;
-  invalidate(service: string, round?: number): Promise<any>;
+  private handleInstantiationResult;
   /**
-   * Gracefully clears all services in the ServiceLocator using invalidation logic.
-   * This method respects service dependencies and ensures proper cleanup order.
-   * Services that depend on others will be invalidated first, then their dependencies.
+   * Waits for an instance holder to be ready and returns the appropriate result.
    *
-   * @param options Optional configuration for the clearing process
-   * @returns Promise that resolves when all services have been cleared
-   */
-  clearAll(options?: ClearAllOptions): Promise<void>;
-  /**
-   * Waits for all services to settle (either created, destroyed, or error state).
+   * @param holder The holder to wait for
+   * @param waiterHolder Optional holder that is doing the waiting (for circular dependency detection)
+   * @param getHolder Optional function to retrieve holders by name (required if waiterHolder is provided)
    */
-  ready(): Promise<void>;
+  private waitForInstanceReady;
   /**
-   * Helper method for InstanceResolver to generate instance names.
-   * This is needed for the factory context creation.
+   * Creates a ServiceInitializationContext for service instantiation.
    */
-  generateInstanceName(token: any, args: any): string;
+  private createServiceInitializationContext;
 }
 //#endregion
 //#region src/container/container.d.mts
 /**
  * Main dependency injection container.
  *
- * Provides a simplified public API for dependency injection, wrapping
- * a ServiceLocator instance. Handles singleton and transient services directly,
+ * Provides a simplified public API for dependency injection.
+ * Handles singleton and transient services directly,
  * while request-scoped services require using beginRequest() to create a ScopedContainer.
  */
-declare class Container implements IContainer {
+declare class Container extends AbstractContainer {
   protected readonly registry: Registry;
   protected readonly logger: Console | null;
   protected readonly injectors: Injectors;
-  private readonly serviceLocator;
+  protected readonly defaultScope = InjectableScope.Singleton;
+  protected readonly requestId: undefined;
+  private readonly storage;
+  private readonly serviceInitializer;
+  private readonly serviceInvalidator;
+  private readonly tokenResolver;
+  private readonly nameResolver;
+  private readonly scopeTracker;
+  private readonly eventBus;
+  private readonly instanceResolver;
   private readonly activeRequestIds;
   constructor(registry?: Registry, logger?: Console | null, injectors?: Injectors);
   private registerSelf;
   /**
    * Gets an instance from the container.
-   * This method has the same type signature as the inject method from get-injectors.mts
-   *
    * NOTE: Request-scoped services cannot be resolved directly from Container.
    * Use beginRequest() to create a ScopedContainer for request-scoped services.
    */
@@ -1120,87 +1147,46 @@ declare class Container implements IContainer {
   get<T>(token: BoundInjectionToken<T, any>): Promise<T>;
   get<T>(token: FactoryInjectionToken<T, any>): Promise<T>;
   /**
-   * Gets an instance with a specific container context.
-   * Used by ScopedContainer to delegate singleton/transient resolution
-   * while maintaining the correct container context for nested inject() calls.
-   *
-   * @internal
-   */
-  getWithContext(token: ClassType | InjectionToken<any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any>, args: unknown, contextContainer: IContainer): Promise<any>;
-  /**
-   * Resolves a request-scoped service for a ScopedContainer.
-   * The service will be stored in the ScopedContainer's request context.
-   *
-   * @internal
-   */
-  resolveForRequest(token: ClassType | InjectionToken<any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any>, args: unknown, scopedContainer: ScopedContainer): Promise<any>;
-  /**
-   * Gets the underlying ServiceLocator instance for advanced usage
-   */
-  getServiceLocator(): ServiceLocator;
-  /**
-   * Gets the registry
-   */
-  getRegistry(): Registry;
-  /**
-   * Invalidates a service and its dependencies
+   * Invalidates a service and its dependencies.
    */
   invalidate(service: unknown): Promise<void>;
   /**
-   * Gets a service holder by instance (reverse lookup)
-   */
-  private getHolderByInstance;
-  /**
-   * Checks if a service is registered in the container
-   */
-  isRegistered(token: any): boolean;
-  /**
-   * Disposes the container and cleans up all resources
+   * Disposes the container and cleans up all resources.
    */
   dispose(): Promise<void>;
-  /**
-   * Waits for all pending operations to complete
-   */
-  ready(): Promise<void>;
   /**
    * @internal
    * Attempts to get an instance synchronously if it already exists.
-   * Returns null if the instance doesn't exist or is not ready.
+   * Overrides base class to support requestId parameter for ScopedContainer compatibility.
    */
-  tryGetSync<T>(token: any, args?: any): T | null;
+  tryGetSync<T>(token: any, args?: any, requestId?: string): T | null;
   /**
    * Begins a new request context and returns a ScopedContainer.
-   *
-   * The ScopedContainer provides isolated request-scoped service resolution
-   * while delegating singleton and transient services to this Container.
-   *
-   * @param requestId Unique identifier for this request
-   * @param metadata Optional metadata for the request
-   * @param priority Priority for resolution (higher = more priority)
-   * @returns A ScopedContainer for this request
    */
-  beginRequest(requestId: string, metadata?: Record<string, any>, priority?: number): ScopedContainer;
+  beginRequest(requestId: string, metadata?: Record<string, any>): ScopedContainer;
   /**
-   * Removes a request ID from the active set.
-   * Called by ScopedContainer when the request ends.
-   *
-   * @internal
-   */
-  removeActiveRequest(requestId: string): void;
-  /**
-   * Gets the set of active request IDs.
+   * Gets all active request IDs.
    */
   getActiveRequestIds(): ReadonlySet<string>;
   /**
-   * Checks if a request ID is currently active.
+   * Checks if a request is active.
    */
   hasActiveRequest(requestId: string): boolean;
   /**
-   * Clears all instances and bindings from the container.
-   * This is useful for testing or resetting the container state.
+   * Removes a request ID from active requests.
+   * Called by ScopedContainer when request ends.
    */
-  clear(): Promise<void>;
+  removeRequestId(requestId: string): void;
+  getStorage(): UnifiedStorage;
+  getServiceInitializer(): ServiceInitializer;
+  getServiceInvalidator(): ServiceInvalidator;
+  getTokenResolver(): TokenResolver;
+  getNameResolver(): NameResolver;
+  getScopeTracker(): ScopeTracker;
+  getEventBus(): LifecycleEventBus;
+  getRegistry(): Registry;
+  getInstanceResolver(): InstanceResolver;
 }
 //#endregion
-export { InjectState as $, InjectableScope as A, ClassTypeWithoutArguments as B, InstanceStatus as C, Registry as D, FactoryRecord as E, ClassTypeWithArgument as F, OptionalInjectionTokenSchemaType as G, InjectionToken as H, ClassTypeWithInstance as I, getInjectors as J, FactoryContext as K, ClassTypeWithInstanceAndArgument as L, BaseInjectionTokenSchemaType as M, BoundInjectionToken as N, globalRegistry as O, ClassType as P, InjectRequest as Q, ClassTypeWithInstanceAndOptionalArgument as R, InstanceHolderError as S, DIErrorCode as T, InjectionTokenSchemaType as U, FactoryInjectionToken as V, InjectionTokenType as W, Factorable as X, IContainer as Y, FactorableWithArgs as Z, InstanceEffect as _, HolderManager as a, UnionToOvlds as at, InstanceHolderCreating as b, DefaultRequestContext as c, createRequestContext as d, IsUnion as et, BaseHolderManager as f, InstanceDestroyListener as g, IHolderStorage as h, Invalidator as i, UnionToIntersection as it, AnyInjectableType as j, InjectableType as k, RequestContext as l, HolderGetResult as m, ServiceLocator as n, PopUnion as nt, LifecycleEventBus as o, HolderReadyResult as p, Injectors as q, TokenProcessor as r, UnionToArray as rt, ScopedContainer as s, Container as t, Join as tt, RequestContextHolder as u, InstanceHolder as v, DIError as w, InstanceHolderDestroying as x, InstanceHolderCreated as y, ClassTypeWithOptionalArgument as z };
-//# sourceMappingURL=container-YPwvmlK2.d.cts.map
+export { ClassTypeWithoutArguments as $, Injectors as A, PopUnion as B, NameResolver as C, Factorable as D, globalRegistry as E, IContainer as F, BaseInjectionTokenSchemaType as G, UnionToIntersection as H, InjectRequest as I, ClassTypeWithArgument as J, BoundInjectionToken as K, InjectState as L, ServiceInitializationContext as M, InjectableType as N, FactorableWithArgs as O, InjectableScope as P, ClassTypeWithOptionalArgument as Q, IsUnion as R, DIErrorCode as S, Registry as T, UnionToOvlds as U, UnionToArray as V, AnyInjectableType as W, ClassTypeWithInstanceAndArgument as X, ClassTypeWithInstance as Y, ClassTypeWithInstanceAndOptionalArgument as Z, InstanceHolderCreating as _, ScopedContainer as a, InstanceStatus as b, ClearAllOptions as c, LifecycleEventBus as d, FactoryInjectionToken as et, HolderGetResult as f, InstanceHolderCreated as g, InstanceHolder as h, ScopeTracker as i, OptionalInjectionTokenSchemaType as it, getInjectors as j, FactoryContext as k, InvalidationOptions as l, InstanceDestroyListener as m, InstanceResolver as n, InjectionTokenSchemaType as nt, UnifiedStorage as o, IHolderStorage as p, ClassType as q, ServiceInitializer as r, InjectionTokenType as rt, TokenResolver as s, Container as t, InjectionToken as tt, ServiceInvalidator as u, InstanceHolderDestroying as v, FactoryRecord as w, DIError as x, InstanceHolderError as y, Join as z };
+//# sourceMappingURL=container-D-0Ho3qL.d.cts.map