sandly 0.0.2 → 0.2.0

package/dist/index.d.ts

@@ -1,10 +1,27 @@
 //#region src/tag.d.ts
 /**
- * Internal symbol used to identify tagged types within the dependency injection system.
- * This symbol is used as a property key to attach metadata to both value tags and class tags.
+ * Type representing a tag identifier (string or symbol).
  * @internal
  */
-declare const TagId: "__tag_id__";
+type TagId = string | symbol;
+/**
+ * Symbol used to identify tagged types within the dependency injection system.
+ * This symbol is used as a property key to attach metadata to both value tags and service tags.
+ *
+ * Note: We can't use a symbol here becuase it produced the following TS error:
+ *  error TS4020: 'extends' clause of exported class 'NotificationService' has or is using private name 'TagIdKey'.
+ *
+ * @internal
+ */
+declare const ValueTagIdKey = "__sandly/ValueTagIdKey__";
+declare const ServiceTagIdKey = "__sandly/ServiceTagIdKey__";
+/**
+ * Internal symbol used to identify the type of a tagged type within the dependency injection system.
+ * This symbol is used as a property key to attach metadata to both value tags and service tags.
+ * It is used to carry the type of the tagged type and should not be used directly.
+ * @internal
+ */
+declare const TagTypeKey: unique symbol;
 /**
  * Type representing a value-based dependency tag.
  *
@@ -18,31 +35,30 @@ declare const TagId: "__tag_id__";
  * @example
  * ```typescript
  * // Creates a value tag for string configuration
- * const ApiKeyTag: ValueTag<string, 'apiKey'> = Tag.of('apiKey')<string>();
+ * const ApiKeyTag: ValueTag<'apiKey', string> = Tag.of('apiKey')<string>();
  *
  * // Register in container
  * container.register(ApiKeyTag, () => 'my-secret-key');
  * ```
  */
-type ValueTag<T, Id extends string | symbol> = Readonly<{
-  readonly [TagId]: Id;
-  /** @internal Phantom type to carry T */
-  readonly __type: T;
-}>;
+interface ValueTag<Id extends TagId, T> {
+  readonly [ValueTagIdKey]: Id;
+  readonly [TagTypeKey]: T;
+}
 /**
  * Type representing a class-based dependency tag.
  *
- * Tagged classes are created by Tag.Class() and serve as both the dependency identifier
+ * Tagged classes are created by Tag.Service() and serve as both the dependency identifier
  * and the constructor for the service. They extend regular classes with tag metadata
  * that the DI system uses for identification and type safety.
  *
- * @template T - The type of instances created by this tagged class
  * @template Id - The unique identifier for this tag (string or symbol)
+ * @template T - The type of instances created by this tagged class
  *
  * @example
  * ```typescript
  * // Creates a tagged class
- * class UserService extends Tag.Class('UserService') {
+ * class UserService extends Tag.Service('UserService') {
  *   getUsers() { return []; }
  * }
  *
@@ -50,25 +66,53 @@ type ValueTag<T, Id extends string | symbol> = Readonly<{
  * container.register(UserService, () => new UserService());
  * ```
  *
- * @internal - Users should use Tag.Class() instead of working with this type directly
+ * @internal - Users should use Tag.Service() instead of working with this type directly
  */
-type TaggedClass<T, Id extends string | symbol> = {
+interface ServiceTag<Id extends TagId, T> {
   new (...args: any[]): T & {
-    readonly [TagId]: Id;
+    readonly [ServiceTagIdKey]: Id;
   };
-  readonly [TagId]: Id;
-};
+  readonly [ServiceTagIdKey]: Id;
+}
 /**
- * Type representing a class-based dependency tag.
+ * Utility type that extracts the service type from any dependency tag.
+ *
+ * This type is essential for type inference throughout the DI system, allowing
+ * the container and layers to automatically determine what type of service
+ * a given tag represents without manual type annotations.
  *
- * This type is a shortcut for TaggedClass<T, string | symbol>.
+ * @template T - Any dependency tag (ValueTag or ServiceTag)
+ * @returns The service type that the tag represents
  *
- * @template T - The type of instances created by this tagged class
- * @returns A tagged class with a string or symbol identifier
+ * @example With value tags
+ * ```typescript
+ * const StringTag = Tag.of('myString')<string>();
+ * const ConfigTag = Tag.of('config')<{ apiKey: string }>();
+ *
+ * type StringService = TagType<typeof StringTag>; // string
+ * type ConfigService = TagType<typeof ConfigTag>; // { apiKey: string }
+ * ```
+ *
+ * @example With service tags
+ * ```typescript
+ * class UserService extends Tag.Service('UserService') {
+ *   getUsers() { return []; }
+ * }
+ *
+ * type UserServiceType = TagType<typeof UserService>; // UserService
+ * ```
+ *
+ * @example Used in container methods
+ * ```typescript
+ * // The container uses TagType internally for type inference
+ * container.register(StringTag, () => 'hello'); // Factory must return string
+ * container.register(UserService, () => new UserService()); // Factory must return UserService
  *
- * @internal - Users should use Tag.Class() instead of working with this type directly
+ * const str: string = await container.resolve(StringTag); // Automatically typed as string
+ * const user: UserService = await container.resolve(UserService); // Automatically typed as UserService
+ * ```
  */
-type ClassTag<T> = TaggedClass<T, string | symbol>;
+type TagType<TTag extends AnyTag> = TTag extends ValueTag<any, infer T> ? T : TTag extends ServiceTag<any, infer T> ? T : never;
 /**
  * Union type representing any valid dependency tag in the system.
  *
@@ -84,15 +128,15 @@ type ClassTag<T> = TaggedClass<T, string | symbol>;
  *
  * @example Class tag
  * ```typescript
- * class DatabaseService extends Tag.Class('DatabaseService') {}
+ * class DatabaseService extends Tag.Service('DatabaseService') {}
  * // DatabaseService satisfies AnyTag
  * ```
  */
-type AnyTag = ValueTag<any, string | symbol> | TaggedClass<any, string | symbol>;
+type AnyTag = ValueTag<TagId, any> | ServiceTag<TagId, any>;
 /**
  * Utility object containing factory functions for creating dependency tags.
  *
- * The Tag object provides the primary API for creating both value tags and class tags
+ * The Tag object provides the primary API for creating both value tags and service tags
  * used throughout the dependency injection system. It's the main entry point for
  * defining dependencies in a type-safe way.
  */
@@ -152,7 +196,7 @@ declare const Tag: {
    * }));
    * ```
    */
-  of: <Id extends string | symbol>(id: Id) => <T>() => ValueTag<T, Id>;
+  of: <Id extends TagId>(id: Id) => <T>() => ValueTag<Id, T>;
   /**
    * Creates an anonymous value tag with a unique symbol identifier.
    *
@@ -186,7 +230,7 @@ declare const Tag: {
    * console.log(ConfigA === ConfigB); // false
    * ```
    */
-  for: <T>() => ValueTag<T, symbol>;
+  for: <T>() => ValueTag<symbol, T>;
   /**
    * Creates a base class that can be extended to create service classes with dependency tags.
    *
@@ -200,7 +244,7 @@ declare const Tag: {
    *
    * @example Basic service class
    * ```typescript
-   * class UserService extends Tag.Class('UserService') {
+   * class UserService extends Tag.Service('UserService') {
    *   getUsers() {
    *     return ['alice', 'bob'];
    *   }
@@ -211,11 +255,11 @@ declare const Tag: {
    *
    * @example Service with dependencies
    * ```typescript
-   * class DatabaseService extends Tag.Class('DatabaseService') {
+   * class DatabaseService extends Tag.Service('DatabaseService') {
    *   query(sql: string) { return []; }
    * }
    *
-   * class UserRepository extends Tag.Class('UserRepository') {
+   * class UserRepository extends Tag.Service('UserRepository') {
    *   constructor(private db: DatabaseService) {
    *     super();
    *   }
@@ -227,25 +271,23 @@ declare const Tag: {
    *
    * container
    *   .register(DatabaseService, () => new DatabaseService())
-   *   .register(UserRepository, async (c) =>
-   *     new UserRepository(await c.get(DatabaseService))
+   *   .register(UserRepository, async (ctx) =>
+   *     new UserRepository(await ctx.resolve(DatabaseService))
    *   );
    * ```
    *
    * @example With symbol identifiers
    * ```typescript
-   * const SERVICE_ID = Symbol('InternalService');
+   * const ServiceId = Symbol('InternalService');
    *
-   * class InternalService extends Tag.Class(SERVICE_ID) {
+   * class InternalService extends Tag.Service(ServiceId) {
    *   doInternalWork() { return 'work'; }
    * }
    * ```
    */
-  Class: <Id extends string | symbol>(id: Id) => TaggedClass<{
-    /** @internal */
-    readonly __type: unknown;
-    readonly __tag_id__: Id;
-  }, Id>;
+  Service: <Id extends TagId>(id: Id) => ServiceTag<Id, {
+    readonly "__sandly/ServiceTagIdKey__": Id;
+  }>;
   /**
    * Extracts the string representation of a tag's identifier.
    *
@@ -253,14 +295,14 @@ declare const Tag: {
    * whether it's a string-based or symbol-based tag. Primarily used internally
    * for error messages and debugging.
    *
-   * @param tag - Any valid dependency tag (value tag or class tag)
+   * @param tag - Any valid dependency tag (value tag or service tag)
    * @returns String representation of the tag's identifier
    *
    * @example
    * ```typescript
    * const StringTag = Tag.of('myString')<string>();
    * const SymbolTag = Tag.for<number>();
-   * class ServiceClass extends Tag.Class('MyService') {}
+   * class ServiceClass extends Tag.Service('MyService') {}
    *
    * console.log(Tag.id(StringTag)); // "myString"
    * console.log(Tag.id(SymbolTag)); // "Symbol()"
@@ -269,65 +311,56 @@ declare const Tag: {
    *
    * @internal - Primarily for internal use in error messages and debugging
    */
-  id: (tag: AnyTag) => string;
+  id: (tag: AnyTag) => TagId;
+  isTag: (tag: unknown) => tag is AnyTag;
 };
 /**
- * Utility type that extracts the service type from any dependency tag.
+ * Unique symbol used to store the original ValueTag in Inject<T> types.
+ * This prevents property name collisions while allowing type-level extraction.
+ */
+declare const InjectSource: unique symbol;
+/**
+ * Helper type for injecting ValueTag dependencies in constructor parameters.
+ * This allows clean specification of ValueTag dependencies while preserving
+ * the original tag information for dependency inference.
  *
- * This type is essential for type inference throughout the DI system, allowing
- * the container and layers to automatically determine what type of service
- * a given tag represents without manual type annotations.
+ * The phantom property is optional to allow normal runtime values to be assignable.
  *
- * @template T - Any dependency tag (ValueTag or TaggedClass)
- * @returns The service type that the tag represents
+ * @template T - A ValueTag type
+ * @returns The value type with optional phantom tag metadata for dependency inference
  *
- * @example With value tags
+ * @example
  * ```typescript
- * const StringTag = Tag.of('myString')<string>();
- * const ConfigTag = Tag.of('config')<{ apiKey: string }>();
- *
- * type StringService = ServiceOf<typeof StringTag>; // string
- * type ConfigService = ServiceOf<typeof ConfigTag>; // { apiKey: string }
- * ```
+ * const ApiKeyTag = Tag.of('apiKey')<string>();
  *
- * @example With class tags
- * ```typescript
- * class UserService extends Tag.Class('UserService') {
- *   getUsers() { return []; }
+ * class UserService extends Tag.Service('UserService') {
+ *   constructor(
+ *     private db: DatabaseService,        // ServiceTag - works automatically
+ *     private apiKey: Inject<typeof ApiKeyTag>  // ValueTag - type is string, tag preserved
+ *   ) {
+ *     super();
+ *   }
  * }
- *
- * type UserServiceType = ServiceOf<typeof UserService>; // UserService
- * ```
- *
- * @example Used in container methods
- * ```typescript
- * // The container uses ServiceOf internally for type inference
- * container.register(StringTag, () => 'hello'); // Factory must return string
- * container.register(UserService, () => new UserService()); // Factory must return UserService
- *
- * const str: string = await container.get(StringTag); // Automatically typed as string
- * const user: UserService = await container.get(UserService); // Automatically typed as UserService
  * ```
  */
-type ServiceOf<T> = T extends ValueTag<infer S, string | symbol> ? S : T extends ClassTag<infer S> ? S : never;
-//#endregion
-//#region src/types.d.ts
-type PromiseOrValue<T> = T | Promise<T>;
-/**
- * Unique symbol used to store the original ValueTag in Inject<T> types.
- * This prevents property name collisions while allowing type-level extraction.
- */
-declare const InjectSource: unique symbol;
+type Inject<T extends ValueTag<TagId, unknown>> = T extends ValueTag<any, infer V> ? V & {
+  readonly [InjectSource]?: T;
+} : never;
 /**
- * Generic interface representing a class constructor.
- *
- * This is primarily used internally for type constraints and validations.
- * Most users should use Tag.Class() instead of working with raw constructors.
- *
- * @template T - The type that the constructor creates
+ * Helper type to extract the original ValueTag from an Inject<T> type.
+ * Since InjectSource is optional, we need to check for both presence and absence.
  * @internal
  */
-
+type ExtractInjectTag<T> = T extends {
+  readonly [InjectSource]?: infer U;
+} ? U : never;
+//#endregion
+//#region src/types.d.ts
+type PromiseOrValue<T> = T | Promise<T>;
+type Contravariant<A> = (_: A) => void;
+type Covariant<A> = (_: never) => A;
+//#endregion
+//#region src/container.d.ts
 /**
  * Type representing a factory function used to create dependency instances.
  *
@@ -343,58 +376,23 @@ declare const InjectSource: unique symbol;
  *
  * @example Synchronous factory
  * ```typescript
- * const factory: Factory<DatabaseService, never> = (container) => {
+ * const factory: Factory<DatabaseService, never> = (ctx) => {
  *   return new DatabaseService('sqlite://memory');
  * };
  * ```
  *
  * @example Asynchronous factory with dependencies
  * ```typescript
- * const factory: Factory<UserService, typeof ConfigTag | typeof DatabaseService> = async (container) => {
+ * const factory: Factory<UserService, typeof ConfigTag | typeof DatabaseService> = async (ctx) => {
  *   const [config, db] = await Promise.all([
- *     container.get(ConfigTag),
- *     container.get(DatabaseService)
+ *     ctx.resolve(ConfigTag),
+ *     ctx.resolve(DatabaseService)
  *   ]);
  *   return new UserService(config, db);
  * };
  * ```
  */
-type Factory<T, TReg extends AnyTag, TScope extends Scope> = (container: IContainer<TReg, TScope>) => PromiseOrValue<T>;
-/**
- * Helper type for injecting ValueTag dependencies in constructor parameters.
- * This allows clean specification of ValueTag dependencies while preserving
- * the original tag information for dependency inference.
- *
- * The phantom property is optional to allow normal runtime values to be assignable.
- *
- * @template T - A ValueTag type
- * @returns The value type with optional phantom tag metadata for dependency inference
- *
- * @example
- * ```typescript
- * const ApiKeyTag = Tag.of('apiKey')<string>();
- *
- * class UserService extends Tag.Class('UserService') {
- *   constructor(
- *     private db: DatabaseService,        // ClassTag - works automatically
- *     private apiKey: Inject<typeof ApiKeyTag>  // ValueTag - type is string, tag preserved
- *   ) {
- *     super();
- *   }
- * }
- * ```
- */
-type Inject<T extends ValueTag<unknown, string | symbol>> = T extends ValueTag<infer V, string | symbol> ? V & {
-  readonly [InjectSource]?: T;
-} : never;
-/**
- * Helper type to extract the original ValueTag from an Inject<T> type.
- * Since InjectSource is optional, we need to check for both presence and absence.
- * @internal
- */
-type ExtractInjectTag<T> = T extends {
-  readonly [InjectSource]?: infer U;
-} ? U : never;
+type Factory<T, TReg extends AnyTag> = (ctx: ResolutionContext<TReg>) => PromiseOrValue<T>;
 /**
  * Type representing a finalizer function used to clean up dependency instances.
  *
@@ -436,19 +434,95 @@ type ExtractInjectTag<T> = T extends {
  * ```
  */
 type Finalizer<T> = (instance: T) => PromiseOrValue<void>;
-type Scope = string | symbol;
-declare const DefaultScope: unique symbol;
-type DefaultScope = typeof DefaultScope;
-//#endregion
-//#region src/container.d.ts
-type DependencyLifecycle<T extends AnyTag, TReg extends AnyTag, TScope extends Scope> = {
-  factory: Factory<ServiceOf<T>, TReg, TScope>;
-  finalizer: Finalizer<ServiceOf<T>>;
+/**
+ * Type representing a complete dependency lifecycle with both factory and finalizer.
+ *
+ * This type is used when registering dependencies that need cleanup. Instead of
+ * passing separate factory and finalizer parameters, you can pass an object
+ * containing both.
+ *
+ * @template T - The dependency tag type
+ * @template TReg - Union type of all dependencies available in the container
+ *
+ * @example Using DependencyLifecycle for registration
+ * ```typescript
+ * class DatabaseConnection extends Tag.Service('DatabaseConnection') {
+ *   async connect() { return; }
+ *   async disconnect() { return; }
+ * }
+ *
+ * const lifecycle: DependencyLifecycle<typeof DatabaseConnection, never> = {
+ *   factory: async () => {
+ *     const conn = new DatabaseConnection();
+ *     await conn.connect();
+ *     return conn;
+ *   },
+ *   finalizer: async (conn) => {
+ *     await conn.disconnect();
+ *   }
+ * };
+ *
+ * Container.empty().register(DatabaseConnection, lifecycle);
+ * ```
+ */
+type DependencyLifecycle<T, TReg extends AnyTag> = {
+  factory: Factory<T, TReg>;
+  finalizer: Finalizer<T>;
 };
-interface IContainer<TReg extends AnyTag, TScope extends Scope = DefaultScope> {
-  register<T extends AnyTag>(tag: T, factoryOrLifecycle: Factory<ServiceOf<T>, TReg, TScope> | DependencyLifecycle<T, TReg, TScope>, scope?: TScope): IContainer<TReg | T, TScope>;
+/**
+ * Union type representing all valid dependency registration specifications.
+ *
+ * A dependency can be registered either as:
+ * - A simple factory function that creates the dependency
+ * - A complete lifecycle object with both factory and finalizer
+ *
+ * @template T - The dependency tag type
+ * @template TReg - Union type of all dependencies available in the container
+ *
+ * @example Simple factory registration
+ * ```typescript
+ * const spec: DependencySpec<typeof UserService, never> =
+ *   () => new UserService();
+ *
+ * Container.empty().register(UserService, spec);
+ * ```
+ *
+ * @example Lifecycle registration
+ * ```typescript
+ * const spec: DependencySpec<typeof DatabaseConnection, never> = {
+ *   factory: () => new DatabaseConnection(),
+ *   finalizer: (conn) => conn.close()
+ * };
+ *
+ * Container.empty().register(DatabaseConnection, spec);
+ * ```
+ */
+type DependencySpec<T extends AnyTag, TReg extends AnyTag> = Factory<TagType<T>, TReg> | DependencyLifecycle<TagType<T>, TReg>;
+/**
+ * Type representing the context available to factory functions during dependency resolution.
+ *
+ * This type contains only the `resolve` and `resolveAll` methods from the container, which are used to retrieve
+ * other dependencies during the creation of a service.
+ *
+ * @template TReg - Union type of all dependencies available in the container
+ */
+type ResolutionContext<TReg extends AnyTag> = Pick<IContainer<TReg>, 'resolve' | 'resolveAll'>;
+declare const ContainerTypeId: unique symbol;
+/**
+ * Interface representing a container that can register and retrieve dependencies.
+ *
+ * @template TReg - Union type of all dependencies available in the container
+ */
+interface IContainer<TReg extends AnyTag = never> {
+  readonly [ContainerTypeId]: {
+    readonly _TReg: Contravariant<TReg>;
+  };
+  register: <T extends AnyTag>(tag: T, spec: DependencySpec<T, TReg>) => IContainer<TReg | T>;
   has(tag: AnyTag): boolean;
-  get<T extends TReg>(tag: T): Promise<ServiceOf<T>>;
+  exists(tag: AnyTag): boolean;
+  resolve: <T extends TReg>(tag: T) => Promise<TagType<T>>;
+  resolveAll: <const T extends readonly TReg[]>(...tags: T) => Promise<{ [K in keyof T]: TagType<T[K]> }>;
+  merge<TTarget extends AnyTag>(other: IContainer<TTarget>): IContainer<TReg | TTarget>;
   destroy(): Promise<void>;
 }
 /**
@@ -462,26 +536,26 @@ interface IContainer<TReg extends AnyTag, TScope extends Scope = DefaultScope> {
  *
  * @template TReg - Union type of all registered dependency tags in this container
  *
- * @example Basic usage with class tags
+ * @example Basic usage with service tags
  * ```typescript
- * import { container, Tag } from 'sandl';
+ * import { container, Tag } from 'sandly';
  *
- * class DatabaseService extends Tag.Class('DatabaseService') {
+ * class DatabaseService extends Tag.Service('DatabaseService') {
  *   query() { return 'data'; }
  * }
  *
- * class UserService extends Tag.Class('UserService') {
+ * class UserService extends Tag.Service('UserService') {
  *   constructor(private db: DatabaseService) {}
  *   getUser() { return this.db.query(); }
  * }
  *
- * const c = container()
+ * const c = Container.empty()
  *   .register(DatabaseService, () => new DatabaseService())
- *   .register(UserService, async (container) =>
- *     new UserService(await container.get(DatabaseService))
+ *   .register(UserService, async (ctx) =>
+ *     new UserService(await ctx.resolve(DatabaseService))
  *   );
  *
- * const userService = await c.get(UserService);
+ * const userService = await c.resolve(UserService);
  * ```
  *
  * @example Usage with value tags
@@ -489,22 +563,22 @@ interface IContainer<TReg extends AnyTag, TScope extends Scope = DefaultScope> {
  * const ApiKeyTag = Tag.of('apiKey')<string>();
  * const ConfigTag = Tag.of('config')<{ dbUrl: string }>();
  *
- * const c = container()
+ * const c = Container.empty()
  *   .register(ApiKeyTag, () => process.env.API_KEY!)
  *   .register(ConfigTag, () => ({ dbUrl: 'postgresql://localhost:5432' }));
  *
- * const apiKey = await c.get(ApiKeyTag);
- * const config = await c.get(ConfigTag);
+ * const apiKey = await c.resolve(ApiKeyTag);
+ * const config = await c.resolve(ConfigTag);
  * ```
  *
  * @example With finalizers for cleanup
  * ```typescript
- * class DatabaseConnection extends Tag.Class('DatabaseConnection') {
+ * class DatabaseConnection extends Tag.Service('DatabaseConnection') {
  *   async connect() { return; }
  *   async disconnect() { return; }
  * }
  *
- * const c = container().register(
+ * const c = Container.empty().register(
  *   DatabaseConnection,
  *   async () => {
  *     const conn = new DatabaseConnection();
@@ -519,43 +593,56 @@ interface IContainer<TReg extends AnyTag, TScope extends Scope = DefaultScope> {
  * ```
  */
 declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
+  readonly [ContainerTypeId]: {
+    readonly _TReg: Contravariant<TReg>;
+  };
   /**
    * Cache of instantiated dependencies as promises.
    * Ensures singleton behavior and supports concurrent access.
    * @internal
    */
-  private readonly cache;
+  protected readonly cache: Map<AnyTag, Promise<unknown>>;
   /**
    * Factory functions for creating dependency instances.
    * @internal
    */
-  private readonly factories;
+  protected readonly factories: Map<AnyTag, Factory<unknown, TReg>>;
   /**
    * Finalizer functions for cleaning up dependencies when the container is destroyed.
    * @internal
    */
-  private readonly finalizers;
+  protected readonly finalizers: Map<AnyTag, Finalizer<any>>;
+  /**
+   * Flag indicating whether this container has been destroyed.
+   * @internal
+   */
+  protected isDestroyed: boolean;
+  static empty(): Container<never>;
   /**
    * Registers a dependency in the container with a factory function and optional finalizer.
    *
    * The factory function receives the current container instance and must return the
    * service instance (or a Promise of it). The container tracks the registration at
-   * the type level, ensuring type safety for subsequent `.get()` calls.
+   * the type level, ensuring type safety for subsequent `.resolve()` calls.
+   *
+   * If a dependency is already registered, this method will override it unless the
+   * dependency has already been instantiated, in which case it will throw an error.
    *
    * @template T - The dependency tag being registered
    * @param tag - The dependency tag (class or value tag)
    * @param factory - Function that creates the service instance, receives container for dependency injection
    * @param finalizer - Optional cleanup function called when container is destroyed
    * @returns A new container instance with the dependency registered
-   * @throws {DependencyContainerError} If the dependency is already registered
+   * @throws {ContainerDestroyedError} If the container has been destroyed
+   * @throws {Error} If the dependency has already been instantiated
    *
    * @example Registering a simple service
    * ```typescript
-   * class LoggerService extends Tag.Class('LoggerService') {
+   * class LoggerService extends Tag.Service('LoggerService') {
    *   log(message: string) { console.log(message); }
    * }
    *
-   * const c = container().register(
+   * const c = Container.empty().register(
    *   LoggerService,
    *   () => new LoggerService()
    * );
@@ -563,26 +650,33 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    *
    * @example Registering with dependencies
    * ```typescript
-   * class UserService extends Tag.Class('UserService') {
+   * class UserService extends Tag.Service('UserService') {
    *   constructor(private db: DatabaseService, private logger: LoggerService) {}
    * }
    *
-   * const c = container()
+   * const c = Container.empty()
    *   .register(DatabaseService, () => new DatabaseService())
    *   .register(LoggerService, () => new LoggerService())
-   *   .register(UserService, async (container) =>
+   *   .register(UserService, async (ctx) =>
    *     new UserService(
-   *       await container.get(DatabaseService),
-   *       await container.get(LoggerService)
+   *       await ctx.resolve(DatabaseService),
+   *       await ctx.resolve(LoggerService)
    *     )
    *   );
    * ```
    *
+   * @example Overriding a dependency
+   * ```typescript
+   * const c = Container.empty()
+   *   .register(DatabaseService, () => new DatabaseService())
+   *   .register(DatabaseService, () => new MockDatabaseService()); // Overrides the previous registration
+   * ```
+   *
    * @example Using value tags
    * ```typescript
    * const ConfigTag = Tag.of('config')<{ apiUrl: string }>();
    *
-   * const c = container().register(
+   * const c = Container.empty().register(
    *   ConfigTag,
    *   () => ({ apiUrl: 'https://api.example.com' })
    * );
@@ -590,12 +684,12 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    *
    * @example With finalizer for cleanup
    * ```typescript
-   * class DatabaseConnection extends Tag.Class('DatabaseConnection') {
+   * class DatabaseConnection extends Tag.Service('DatabaseConnection') {
    *   async connect() { return; }
    *   async close() { return; }
    * }
    *
-   * const c = container().register(
+   * const c = Container.empty().register(
    *   DatabaseConnection,
    *   async () => {
    *     const conn = new DatabaseConnection();
@@ -606,27 +700,30 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * );
    * ```
    */
-  register<T extends AnyTag>(tag: T, factoryOrLifecycle: Factory<ServiceOf<T>, TReg, DefaultScope> | DependencyLifecycle<T, TReg, DefaultScope>): IContainer<TReg | T>;
+  register<T extends AnyTag>(tag: T, spec: DependencySpec<T, TReg>): Container<TReg | T>;
   /**
-   * Checks if a dependency has been instantiated (cached) in the container.
+   * Checks if a dependency has been registered in the container.
    *
-   * Note: This returns `true` only after the dependency has been created via `.get()`.
-   * A registered but not-yet-instantiated dependency will return `false`.
+   * This returns `true` if the dependency has been registered via `.register()`,
+   * regardless of whether it has been instantiated yet.
    *
    * @param tag - The dependency tag to check
-   * @returns `true` if the dependency has been instantiated and cached, `false` otherwise
+   * @returns `true` if the dependency has been registered, `false` otherwise
    *
    * @example
    * ```typescript
-   * const c = container().register(DatabaseService, () => new DatabaseService());
-   *
-   * console.log(c.has(DatabaseService)); // false - not instantiated yet
-   *
-   * await c.get(DatabaseService);
-   * console.log(c.has(DatabaseService)); // true - now instantiated and cached
+   * const c = Container.empty().register(DatabaseService, () => new DatabaseService());
+   * console.log(c.has(DatabaseService)); // true
    * ```
    */
   has(tag: AnyTag): boolean;
+  /**
+   * Checks if a dependency has been instantiated (cached) in the container.
+   *
+   * @param tag - The dependency tag to check
+   * @returns true if the dependency has been instantiated, false otherwise
+   */
+  exists(tag: AnyTag): boolean;
   /**
    * Retrieves a dependency instance from the container, creating it if necessary.
    *
@@ -646,10 +743,10 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    *
    * @example Basic usage
    * ```typescript
-   * const c = container()
+   * const c = Container.empty()
    *   .register(DatabaseService, () => new DatabaseService());
    *
-   * const db = await c.get(DatabaseService);
+   * const db = await c.resolve(DatabaseService);
    * db.query('SELECT * FROM users');
    * ```
    *
@@ -657,9 +754,9 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * ```typescript
    * // All three calls will receive the same instance
    * const [db1, db2, db3] = await Promise.all([
-   *   c.get(DatabaseService),
-   *   c.get(DatabaseService),
-   *   c.get(DatabaseService)
+   *   c.resolve(DatabaseService),
+   *   c.resolve(DatabaseService),
+   *   c.resolve(DatabaseService)
    * ]);
    *
    * console.log(db1 === db2 === db3); // true
@@ -667,23 +764,99 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    *
    * @example Dependency injection in factories
    * ```typescript
-   * const c = container()
+   * const c = Container.empty()
    *   .register(DatabaseService, () => new DatabaseService())
-   *   .register(UserService, async (container) => {
-   *     const db = await container.get(DatabaseService);
+   *   .register(UserService, async (ctx) => {
+   *     const db = await ctx.resolve(DatabaseService);
    *     return new UserService(db);
    *   });
    *
-   * const userService = await c.get(UserService);
+   * const userService = await c.resolve(UserService);
+   * ```
+   */
+  resolve<T extends TReg>(tag: T): Promise<TagType<T>>;
+  /**
+   * Resolves multiple dependencies concurrently using Promise.all.
+   *
+   * This method takes a variable number of dependency tags and resolves all of them concurrently,
+   * returning a tuple with the resolved instances in the same order as the input tags.
+   * The method maintains all the same guarantees as the individual resolve method:
+   * singleton behavior, circular dependency detection, and proper error handling.
+   *
+   * @template T - The tuple type of dependency tags to resolve
+   * @param tags - Variable number of dependency tags to resolve
+   * @returns Promise resolving to a tuple of service instances in the same order
+   * @throws {ContainerDestroyedError} If the container has been destroyed
+   * @throws {UnknownDependencyError} If any dependency is not registered
+   * @throws {CircularDependencyError} If a circular dependency is detected
+   * @throws {DependencyCreationError} If any factory function throws an error
+   *
+   * @example Basic usage
+   * ```typescript
+   * const c = Container.empty()
+   *   .register(DatabaseService, () => new DatabaseService())
+   *   .register(LoggerService, () => new LoggerService());
+   *
+   * const [db, logger] = await c.resolveAll(DatabaseService, LoggerService);
+   * ```
+   *
+   * @example Mixed tag types
+   * ```typescript
+   * const ApiKeyTag = Tag.of('apiKey')<string>();
+   * const c = Container.empty()
+   *   .register(ApiKeyTag, () => 'secret-key')
+   *   .register(UserService, () => new UserService());
+   *
+   * const [apiKey, userService] = await c.resolveAll(ApiKeyTag, UserService);
+   * ```
+   *
+   * @example Empty array
+   * ```typescript
+   * const results = await c.resolveAll(); // Returns empty array
+   * ```
+   */
+  resolveAll<const T extends readonly TReg[]>(...tags: T): Promise<{ [K in keyof T]: TagType<T[K]> }>;
+  /**
+   * Copies all registrations from this container to a target container.
+   *
+   * @internal
+   * @param target - The container to copy registrations to
+   * @throws {ContainerDestroyedError} If this container has been destroyed
+   */
+  copyTo<TTarget extends AnyTag>(target: Container<TTarget>): void;
+  /**
+   * Creates a new container by merging this container's registrations with another container.
+   *
+   * This method creates a new container that contains all registrations from both containers.
+   * If there are conflicts (same dependency registered in both containers), this
+   * container's registration will take precedence.
+   *
+   * **Important**: Only the registrations are copied, not any cached instances.
+   * The new container starts with an empty instance cache.
+   *
+   * @param other - The container to merge with
+   * @returns A new container with combined registrations
+   * @throws {ContainerDestroyedError} If this container has been destroyed
+   *
+   * @example Merging containers
+   * ```typescript
+   * const container1 = Container.empty()
+   *   .register(DatabaseService, () => new DatabaseService());
+   *
+   * const container2 = Container.empty()
+   *   .register(UserService, () => new UserService());
+   *
+   * const merged = container1.merge(container2);
+   * // merged has both DatabaseService and UserService
    * ```
    */
-  get<T extends TReg>(tag: T): Promise<ServiceOf<T>>;
+  merge<TTarget extends AnyTag>(other: Container<TTarget>): Container<TReg | TTarget>;
   /**
-   * Destroys all instantiated dependencies by calling their finalizers, then clears the instance cache.
+   * Destroys all instantiated dependencies by calling their finalizers and makes the container unusable.
    *
-   * **Important: This method preserves the container structure (factories and finalizers) for reuse.**
-   * The container can be used again after destruction to create fresh instances following the same
-   * dependency patterns.
+   * **Important: After calling destroy(), the container becomes permanently unusable.**
+   * Any subsequent calls to register(), get(), or destroy() will throw a ContainerError.
+   * This ensures proper cleanup and prevents runtime errors from accessing destroyed resources.
    *
    * All finalizers for instantiated dependencies are called concurrently using Promise.allSettled()
    * for maximum cleanup performance.
@@ -695,11 +868,11 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * dependencies are cleaned up.
    *
    * @returns Promise that resolves when all cleanup is complete
-   * @throws {DependencyContainerFinalizationError} If any finalizers fail during cleanup
+   * @throws {DependencyFinalizationError} If any finalizers fail during cleanup
    *
-   * @example Basic cleanup and reuse
+   * @example Basic cleanup
    * ```typescript
-   * const c = container()
+   * const c = Container.empty()
    *   .register(DatabaseConnection,
    *     async () => {
    *       const conn = new DatabaseConnection();
@@ -709,24 +882,32 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    *     (conn) => conn.disconnect() // Finalizer
    *   );
    *
-   * // First use cycle
-   * const db1 = await c.get(DatabaseConnection);
-   * await c.destroy(); // Calls conn.disconnect(), clears cache
+   * const db = await c.resolve(DatabaseConnection);
+   * await c.destroy(); // Calls conn.disconnect(), container becomes unusable
    *
-   * // Container can be reused - creates fresh instances
-   * const db2 = await c.get(DatabaseConnection); // New connection
-   * expect(db2).not.toBe(db1); // Different instances
+   * // This will throw an error
+   * try {
+   *   await c.resolve(DatabaseConnection);
+   * } catch (error) {
+   *   console.log(error.message); // "Cannot resolve dependencies from a destroyed container"
+   * }
    * ```
    *
-   * @example Multiple destroy/reuse cycles
+   * @example Application shutdown
    * ```typescript
-   * const c = container().register(UserService, () => new UserService());
-   *
-   * for (let i = 0; i < 5; i++) {
-   *   const user = await c.get(UserService);
-   *   // ... use service ...
-   *   await c.destroy(); // Clean up, ready for next cycle
-   * }
+   * const appContainer Container.empty
+   *   .register(DatabaseService, () => new DatabaseService())
+   *   .register(HTTPServer, async (ctx) => new HTTPServer(await ctx.resolve(DatabaseService)));
+   *
+   * // During application shutdown
+   * process.on('SIGTERM', async () => {
+   *   try {
+   *     await appContainer.destroy(); // Clean shutdown of all services
+   *   } catch (error) {
+   *     console.error('Error during shutdown:', error);
+   *   }
+   *   process.exit(0);
+   * });
    * ```
    *
    * @example Handling cleanup errors
@@ -738,138 +919,241 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    *     console.error('Some dependencies failed to clean up:', error.detail.errors);
    *   }
    * }
-   * // Container is still reusable even after finalizer errors
+   * // Container is destroyed regardless of finalizer errors
    * ```
    */
   destroy(): Promise<void>;
 }
-declare class ScopedContainer<TReg extends AnyTag, TScope extends Scope> implements IContainer<TReg, TScope> {
-  private readonly scope;
-  private readonly parent;
-  private readonly children;
-  /**
-   * Cache of instantiated dependencies as promises for this scope.
-   * @internal
-   */
-  private readonly cache;
-  /**
-   * Factory functions for creating dependency instances in this scope.
-   * @internal
-   */
-  private readonly factories;
-  /**
-   * Finalizer functions for cleaning up dependencies when this scope is destroyed.
-   * @internal
-   */
-  private readonly finalizers;
-  constructor(parent: IContainer<any, any> | null, scope: TScope);
-  /**
-   * Registers a dependency in the specified scope within this container's scope chain.
-   *
-   * If no scope is specified, registers in the current (leaf) scope. If a scope is specified,
-   * delegates to the parent container if the target scope doesn't match the current scope.
-   *
-   * This allows registering dependencies at different scope levels from any container
-   * in the scope chain, providing flexibility for dependency organization.
-   *
-   * @param tag - The dependency tag to register
-   * @param factory - Factory function to create the dependency
-   * @param finalizer - Optional cleanup function
-   * @param scope - Target scope for registration (defaults to current scope)
-   * @returns This container with updated type information
-   *
-   * @example Registering in different scopes
-   * ```typescript
-   * const runtime = scopedContainer('runtime');
-   * const request = runtime.child('request');
-   *
-   * // Register in current (request) scope
-   * request.register(RequestService, () => new RequestService());
-   *
-   * // Register in runtime scope from request container - delegates to parent
-   * request.register(DatabaseService, () => new DatabaseService(), undefined, 'runtime');
-   * ```
-   */
-  register<T extends AnyTag>(tag: T, factoryOrLifecycle: Factory<ServiceOf<T>, TReg, TScope> | DependencyLifecycle<T, TReg, TScope>, scope?: TScope): ScopedContainer<TReg | T, TScope>;
-  /**
-   * Checks if a dependency has been instantiated in this scope or any parent scope.
-   *
-   * This method checks the current scope first, then walks up the parent chain.
-   * Returns true only if the dependency has been created and cached somewhere in the scope hierarchy.
-   */
-  has(tag: AnyTag): boolean;
+//#endregion
+//#region src/errors.d.ts
+type ErrorProps = {
+  cause?: unknown;
+  detail?: Record<string, unknown>;
+};
+type ErrorDump = {
+  name: string;
+  message: string;
+  stack?: string;
+  error: {
+    name: string;
+    message: string;
+    detail: Record<string, unknown>;
+    cause?: unknown;
+  };
+};
+declare class BaseError extends Error {
+  detail: Record<string, unknown> | undefined;
+  constructor(message: string, {
+    cause,
+    detail
+  }?: ErrorProps);
+  static ensure(error: unknown): BaseError;
+  dump(): ErrorDump;
+  dumps(): string;
+}
+/**
+ * Base error class for all dependency container related errors.
+ *
+ * This extends the framework's BaseError to provide consistent error handling
+ * and structured error information across the dependency injection system.
+ *
+ * @example Catching DI errors
+ * ```typescript
+ * try {
+ *   await container.resolve(SomeService);
+ * } catch (error) {
+ *   if (error instanceof ContainerError) {
+ *     console.error('DI Error:', error.message);
+ *     console.error('Details:', error.detail);
+ *   }
+ * }
+ * ```
+ */
+declare class ContainerError extends BaseError {}
+/**
+ * Error thrown when attempting to register a dependency that has already been instantiated.
+ *
+ * This error occurs when calling `container.register()` for a tag that has already been instantiated.
+ * Registration must happen before any instantiation occurs, as cached instances would still be used
+ * by existing dependencies.
+ */
+declare class DependencyAlreadyInstantiatedError extends ContainerError {}
+/**
+ * Error thrown when attempting to use a container that has been destroyed.
+ *
+ * This error occurs when calling `container.resolve()`, `container.register()`, or `container.destroy()`
+ * on a container that has already been destroyed. It indicates a programming error where the container
+ * is being used after it has been destroyed.
+ */
+declare class ContainerDestroyedError extends ContainerError {}
+/**
+ * Error thrown when attempting to retrieve a dependency that hasn't been registered.
+ *
+ * This error occurs when calling `container.resolve(Tag)` for a tag that was never
+ * registered via `container.register()`. It indicates a programming error where
+ * the dependency setup is incomplete.
+ *
+ * @example
+ * ```typescript
+ * const c = Container.empty(); // Empty container
+ *
+ * try {
+ *   await c.resolve(UnregisteredService); // This will throw
+ * } catch (error) {
+ *   if (error instanceof UnknownDependencyError) {
+ *     console.error('Missing dependency:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class UnknownDependencyError extends ContainerError {
   /**
-   * Retrieves a dependency instance, resolving from the current scope or parent scopes.
+   * @internal
+   * Creates an UnknownDependencyError for the given tag.
    *
-   * Resolution strategy:
-   * 1. Check cache in current scope
-   * 2. Check if factory exists in current scope - if so, create instance here
-   * 3. Otherwise, delegate to parent scope
-   * 4. If no parent or parent doesn't have it, throw UnknownDependencyError
+   * @param tag - The dependency tag that wasn't found
    */
-  get<T extends TReg>(tag: T): Promise<ServiceOf<T>>;
+  constructor(tag: AnyTag);
+}
+/**
+ * Error thrown when a circular dependency is detected during dependency resolution.
+ *
+ * This occurs when service A depends on service B, which depends on service A (directly
+ * or through a chain of dependencies). The error includes the full dependency chain
+ * to help identify the circular reference.
+ *
+ * @example Circular dependency scenario
+ * ```typescript
+ * class ServiceA extends Tag.Service('ServiceA') {}
+ * class ServiceB extends Tag.Service('ServiceB') {}
+ *
+ * const c = Container.empty()
+ *   .register(ServiceA, async (ctx) =>
+ *     new ServiceA(await ctx.resolve(ServiceB)) // Depends on B
+ *   )
+ *   .register(ServiceB, async (ctx) =>
+ *     new ServiceB(await ctx.resolve(ServiceA)) // Depends on A - CIRCULAR!
+ *   );
+ *
+ * try {
+ *   await c.resolve(ServiceA);
+ * } catch (error) {
+ *   if (error instanceof CircularDependencyError) {
+ *     console.error('Circular dependency:', error.message);
+ *     // Output: "Circular dependency detected for ServiceA: ServiceA -> ServiceB -> ServiceA"
+ *   }
+ * }
+ * ```
+ */
+declare class CircularDependencyError extends ContainerError {
   /**
-   * Destroys this scoped container and its children, preserving the container structure for reuse.
-   *
-   * This method ensures proper cleanup order while maintaining reusability:
-   * 1. Destroys all child scopes first (they may depend on parent scope dependencies)
-   * 2. Then calls finalizers for dependencies created in this scope
-   * 3. Clears only instance caches - preserves factories, finalizers, and child structure
+   * @internal
+   * Creates a CircularDependencyError with the dependency chain information.
    *
-   * Child destruction happens first to ensure dependencies don't get cleaned up
-   * before their dependents.
+   * @param tag - The tag where the circular dependency was detected
+   * @param dependencyChain - The chain of dependencies that led to the circular reference
    */
-  destroy(): Promise<void>;
+  constructor(tag: AnyTag, dependencyChain: AnyTag[]);
+}
+/**
+ * Error thrown when a dependency factory function throws an error during instantiation.
+ *
+ * This wraps the original error with additional context about which dependency
+ * failed to be created. The original error is preserved as the `cause` property.
+ *
+ * @example Factory throwing error
+ * ```typescript
+ * class DatabaseService extends Tag.Service('DatabaseService') {}
+ *
+ * const c = Container.empty().register(DatabaseService, () => {
+ *   throw new Error('Database connection failed');
+ * });
+ *
+ * try {
+ *   await c.resolve(DatabaseService);
+ * } catch (error) {
+ *   if (error instanceof DependencyCreationError) {
+ *     console.error('Failed to create:', error.message);
+ *     console.error('Original error:', error.cause);
+ *   }
+ * }
+ * ```
+ */
+declare class DependencyCreationError extends ContainerError {
   /**
-   * Creates a child scoped container.
+   * @internal
+   * Creates a DependencyCreationError wrapping the original factory error.
    *
-   * Child containers inherit access to parent dependencies but maintain
-   * their own scope for new registrations and instance caching.
+   * @param tag - The tag of the dependency that failed to be created
+   * @param error - The original error thrown by the factory function
    */
-  child<TChildScope extends Scope>(scope: TChildScope): ScopedContainer<TReg, TScope | TChildScope>;
+  constructor(tag: AnyTag, error: unknown);
 }
 /**
- * Creates a new empty dependency injection container.
+ * Error thrown when one or more finalizers fail during container destruction.
  *
- * This is a convenience factory function that creates a new DependencyContainer instance.
- * The returned container starts with no registered dependencies and the type parameter
- * defaults to `never`, indicating no dependencies are available for retrieval yet.
+ * This error aggregates multiple finalizer failures that occurred during
+ * `container.destroy()`. Even if some finalizers fail, the container cleanup
+ * process continues and this error contains details of all failures.
  *
- * @returns A new empty DependencyContainer instance
- *
- * @example
+ * @example Handling finalization errors
  * ```typescript
- * import { container, Tag } from 'sandl';
- *
- * class DatabaseService extends Tag.Class('DatabaseService') {}
- * class UserService extends Tag.Class('UserService') {}
- *
- * const c = container()
- *   .register(DatabaseService, () => new DatabaseService())
- *   .register(UserService, async (container) =>
- *     new UserService(await container.get(DatabaseService))
- *   );
- *
- * const userService = await c.get(UserService);
+ * try {
+ *   await container.destroy();
+ * } catch (error) {
+ *   if (error instanceof DependencyFinalizationError) {
+ *     console.error('Some finalizers failed');
+ *     console.error('Error details:', error.detail.errors);
+ *   }
+ * }
  * ```
  */
-declare function container(): Container<never>;
-declare function scopedContainer<TScope extends Scope>(scope: TScope): ScopedContainer<never, TScope>;
+declare class DependencyFinalizationError extends ContainerError {
+  /**
+   * @internal
+   * Creates a DependencyFinalizationError aggregating multiple finalizer failures.
+   *
+   * @param errors - Array of errors thrown by individual finalizers
+   */
+  constructor(errors: unknown[]);
+}
 //#endregion
 //#region src/layer.d.ts
+/**
+ * The most generic layer type that accepts any concrete layer.
+ */
+type AnyLayer = Layer<any, any>;
+/**
+ * The type ID for the Layer interface.
+ */
+declare const LayerTypeId: unique symbol;
 /**
  * A dependency layer represents a reusable, composable unit of dependency registrations.
  * Layers allow you to organize your dependency injection setup into logical groups
  * that can be combined and reused across different contexts.
  *
+ * ## Type Variance
+ *
+ * The Layer interface uses TypeScript's variance annotations to enable safe substitutability:
+ *
+ * ### TRequires (covariant)
+ * A layer requiring fewer dependencies can substitute one requiring more:
+ * - `Layer<never, X>` can be used where `Layer<A | B, X>` is expected
+ * - Intuition: A service that needs nothing is more flexible than one that needs specific deps
+ *
+ * ### TProvides (contravariant)
+ * A layer providing more services can substitute one providing fewer:
+ * - `Layer<X, A | B>` can be used where `Layer<X, A>` is expected
+ * - Intuition: A service that gives you extra things is compatible with expecting fewer things
+ *
  * @template TRequires - The union of tags this layer requires to be satisfied by other layers
  * @template TProvides - The union of tags this layer provides/registers
  *
  * @example Basic layer usage
  * ```typescript
- * import { layer, Tag, container } from 'sandl';
+ * import { layer, Tag, container } from 'sandly';
  *
- * class DatabaseService extends Tag.Class('DatabaseService') {
+ * class DatabaseService extends Tag.Service('DatabaseService') {
  *   query() { return 'data'; }
  * }
  *
@@ -879,70 +1163,126 @@ declare function scopedContainer<TScope extends Scope>(scope: TScope): ScopedCon
  * );
  *
  * // Apply the layer to a container
- * const c = container();
- * const finalContainer = databaseLayer().register(c);
+ * const c = Container.empty();
+ * const finalContainer = databaseLayer.register(c);
  *
- * const db = await finalContainer.get(DatabaseService);
+ * const db = await finalContainer.resolve(DatabaseService);
  * ```
  *
- * @example Layer composition
+ * @example Layer composition with variance
  * ```typescript
  * // Layer that requires DatabaseService and provides UserService
  * const userLayer = layer<typeof DatabaseService, typeof UserService>((container) =>
- *   container.register(UserService, async (c) =>
- *     new UserService(await c.get(DatabaseService))
+ *   container.register(UserService, async (ctx) =>
+ *     new UserService(await ctx.resolve(DatabaseService))
  *   )
  * );
  *
- * // Compose layers: database layer provides what user layer needs
- * const appLayer = databaseLayer().to(userLayer());
+ * // Compose layers: provide database layer to user layer
+ * const appLayer = userLayer.provide(databaseLayer);
  * ```
  */
-interface Layer<TRequires extends AnyTag = never, TProvides extends AnyTag = never> {
+interface Layer<TRequires extends AnyTag, TProvides extends AnyTag> {
+  readonly [LayerTypeId]?: {
+    readonly _TRequires: Covariant<TRequires>;
+    readonly _TProvides: Contravariant<TProvides>;
+  };
   /**
    * Applies this layer's registrations to the given container.
    *
-   * @param container - The container to register dependencies into
-   * @returns A new container with this layer's dependencies registered
+   * ## Generic Container Support
    *
-   * @example
+   * The signature uses `TContainer extends AnyTag` to accept containers with any existing
+   * services while preserving type information. The container must provide at least this
+   * layer's requirements (`TRequires`) but can have additional services (`TContainer`).
+   *
+   * Result container has: `TRequires | TContainer | TProvides` - everything that was
+   * already there plus this layer's new provisions.
+   *
+   * @param container - The container to register dependencies into (must satisfy TRequires)
+   * @returns A new container with this layer's dependencies registered and all existing services preserved
+   *
+   * @example Basic usage
    * ```typescript
-   * const container = container();
-   * const updatedContainer = myLayer.register(container);
+   * const c = Container.empty();
+   * const updatedContainer = myLayer.register(c);
+   * ```
+   *
+   * @example With existing services preserved
+   * ```typescript
+   * const baseContainer = Container.empty()
+   *   .register(ExistingService, () => new ExistingService());
+   *
+   * const enhanced = myLayer.register(baseContainer);
+   * // Enhanced container has both ExistingService and myLayer's provisions
    * ```
    */
-  register: <TScope extends Scope>(container: IContainer<TRequires, TScope>) => IContainer<TRequires | TProvides, TScope>;
+  register: <TContainer extends AnyTag>(container: IContainer<TRequires | TContainer>) => IContainer<TRequires | TContainer | TProvides>;
   /**
-   * Composes this layer with a target layer, creating a pipeline where this layer's
-   * provisions satisfy the target layer's requirements. This creates a dependency
-   * flow from source → target.
+   * Provides a dependency layer to this layer, creating a pipeline where the dependency layer's
+   * provisions satisfy this layer's requirements. This creates a dependency flow from dependency → this.
    *
-   * Type-safe: The target layer's requirements must be satisfiable by this layer's
+   * Type-safe: This layer's requirements must be satisfiable by the dependency layer's
    * provisions and any remaining external requirements.
    *
-   * @template TTargetRequires - What the target layer requires
-   * @template TTargetProvides - What the target layer provides
-   * @param target - The layer to compose with
-   * @returns A new composed layer
+   * @template TDepRequires - What the dependency layer requires
+   * @template TDepProvides - What the dependency layer provides
+   * @param dependency - The layer to provide as a dependency
+   * @returns A new composed layer that only exposes this layer's provisions
    *
    * @example Simple composition
    * ```typescript
    * const configLayer = layer<never, typeof ConfigTag>(...);
    * const dbLayer = layer<typeof ConfigTag, typeof DatabaseService>(...);
    *
-   * // Config provides what database needs
-   * const infraLayer = configLayer().to(dbLayer());
+   * // Provide config to database layer
+   * const infraLayer = dbLayer.provide(configLayer);
+   * ```
+   *
+   * @example Multi-level composition (reads naturally left-to-right)
+   * ```typescript
+   * const appLayer = apiLayer
+   *   .provide(serviceLayer)
+   *   .provide(databaseLayer)
+   *   .provide(configLayer);
+   * ```
+   */
+  provide: <TDepRequires extends AnyTag, TDepProvides extends AnyTag>(dependency: Layer<TDepRequires, TDepProvides>) => Layer<TDepRequires | Exclude<TRequires, TDepProvides>, TProvides>;
+  /**
+   * Provides a dependency layer to this layer and merges the provisions.
+   * Unlike `.provide()`, this method includes both this layer's provisions and the dependency layer's
+   * provisions in the result type. This is useful when you want to expose services from both layers.
+   *
+   * Type-safe: This layer's requirements must be satisfiable by the dependency layer's
+   * provisions and any remaining external requirements.
+   *
+   * @template TDepRequires - What the dependency layer requires
+   * @template TDepProvides - What the dependency layer provides
+   * @param dependency - The layer to provide as a dependency
+   * @returns A new composed layer that provides services from both layers
+   *
+   * @example Providing with merged provisions
+   * ```typescript
+   * const configLayer = layer<never, typeof ConfigTag>(...);
+   * const dbLayer = layer<typeof ConfigTag, typeof DatabaseService>(...);
+   *
+   * // Provide config to database layer, and both services are available
+   * const infraLayer = dbLayer.provideMerge(configLayer);
+   * // Type: Layer<never, typeof ConfigTag | typeof DatabaseService>
    * ```
    *
-   * @example Multi-level composition
+   * @example Difference from .provide()
    * ```typescript
-   * const appLayer = configLayer()
-   *   .to(databaseLayer())
-   *   .to(serviceLayer())
-   *   .to(apiLayer());
+   * // .provide() only exposes this layer's provisions:
+   * const withProvide = dbLayer.provide(configLayer);
+   * // Type: Layer<never, typeof DatabaseService>
+   *
+   * // .provideMerge() exposes both layers' provisions:
+   * const withProvideMerge = dbLayer.provideMerge(configLayer);
+   * // Type: Layer<never, typeof ConfigTag | typeof DatabaseService>
    * ```
    */
-  to: <TTargetRequires extends AnyTag, TTargetProvides extends AnyTag>(target: Layer<TTargetRequires, TTargetProvides>) => Layer<TRequires | Exclude<TTargetRequires, TProvides>, TProvides | TTargetProvides>;
+  provideMerge: <TDepRequires extends AnyTag, TDepProvides extends AnyTag>(dependency: Layer<TDepRequires, TDepProvides>) => Layer<TDepRequires | Exclude<TRequires, TDepProvides>, TProvides | TDepProvides>;
   /**
    * Merges this layer with another layer, combining their requirements and provisions.
    * This is useful for combining independent layers that don't have a dependency
@@ -959,42 +1299,33 @@ interface Layer<TRequires extends AnyTag = never, TProvides extends AnyTag = nev
    * const loggingLayer = layer<never, typeof LoggerService>(...);
    *
    * // Combine infrastructure layers
-   * const infraLayer = persistenceLayer().and(loggingLayer());
+   * const infraLayer = persistenceLayer.merge(loggingLayer);
    * ```
    *
    * @example Building complex layer combinations
    * ```typescript
-   * const appInfraLayer = persistenceLayer()
-   *   .and(messagingLayer())
-   *   .and(observabilityLayer());
+   * const appInfraLayer = persistenceLayer
+   *   .merge(messagingLayer)
+   *   .merge(observabilityLayer);
    * ```
    */
-  and: <TOtherRequires extends AnyTag, TOtherProvides extends AnyTag>(other: Layer<TOtherRequires, TOtherProvides>) => Layer<TRequires | TOtherRequires, TProvides | TOtherProvides>;
+  merge: <TOtherRequires extends AnyTag, TOtherProvides extends AnyTag>(other: Layer<TOtherRequires, TOtherProvides>) => Layer<TRequires | TOtherRequires, TProvides | TOtherProvides>;
 }
-/**
- * A factory function for creating layers.
- *
- * @template TRequires - The union of tags this layer requires
- * @template TProvides - The union of tags this layer provides
- * @template TParams - Optional parameters that can be passed to configure the layer
- */
-type LayerFactory<TRequires extends AnyTag, TProvides extends AnyTag, TParams = undefined> = TParams extends undefined ? () => Layer<TRequires, TProvides> : (params: TParams) => Layer<TRequires, TProvides>;
 /**
  * Creates a new dependency layer that encapsulates a set of dependency registrations.
  * Layers are the primary building blocks for organizing and composing dependency injection setups.
  *
  * @template TRequires - The union of dependency tags this layer requires from other layers or external setup
  * @template TProvides - The union of dependency tags this layer registers/provides
- * @template TParams - Optional parameters that can be passed to configure the layer
  *
- * @param register - Function that performs the dependency registrations. Receives a container and optional params.
- * @returns A layer factory function. If TParams is undefined, returns a parameterless function. Otherwise returns a function that takes TParams.
+ * @param register - Function that performs the dependency registrations. Receives a container.
+ * @returns The layer instance.
  *
- * @example Simple layer without parameters
+ * @example Simple layer
  * ```typescript
- * import { layer, Tag } from '@/di/layer.js';
+ * import { layer, Tag } from 'sandly';
  *
- * class DatabaseService extends Tag.Class('DatabaseService') {
+ * class DatabaseService extends Tag.Service('DatabaseService') {
  *   constructor(private url: string = 'sqlite://memory') {}
  *   query() { return 'data'; }
  * }
@@ -1005,37 +1336,7 @@ type LayerFactory<TRequires extends AnyTag, TProvides extends AnyTag, TParams =
  * );
  *
  * // Usage
- * const dbLayerInstance = databaseLayer(); // No parameters needed
- * ```
- *
- * @example Layer with dependencies
- * ```typescript
- * const ConfigTag = Tag.of('config')<{ dbUrl: string }>();
- *
- * // Layer that requires ConfigTag and provides DatabaseService
- * const databaseLayer = layer<typeof ConfigTag, typeof DatabaseService>((container) =>
- *   container.register(DatabaseService, async (c) => {
- *     const config = await c.get(ConfigTag);
- *     return new DatabaseService(config.dbUrl);
- *   })
- * );
- * ```
- *
- * @example Parameterized layer
- * ```typescript
- * interface DatabaseConfig {
- *   host: string;
- *   port: number;
- * }
- *
- * // Layer that takes configuration parameters
- * const databaseLayer = layer<never, typeof DatabaseService, DatabaseConfig>(
- *   (container, config) =>
- *     container.register(DatabaseService, () => new DatabaseService(config))
- * );
- *
- * // Usage with parameters
- * const dbLayerInstance = databaseLayer({ host: 'localhost', port: 5432 });
+ * const dbLayerInstance = databaseLayer;
  * ```
  *
  * @example Complex application layer structure
@@ -1049,37 +1350,45 @@ type LayerFactory<TRequires extends AnyTag, TProvides extends AnyTag, TParams =
  * const infraLayer = layer<typeof ConfigTag, typeof DatabaseService | typeof CacheService>(
  *   (container) =>
  *     container
- *       .register(DatabaseService, async (c) => new DatabaseService(await c.get(ConfigTag)))
- *       .register(CacheService, async (c) => new CacheService(await c.get(ConfigTag)))
+ *       .register(DatabaseService, async (ctx) => new DatabaseService(await ctx.resolve(ConfigTag)))
+ *       .register(CacheService, async (ctx) => new CacheService(await ctx.resolve(ConfigTag)))
  * );
  *
  * // Service layer (requires infrastructure)
  * const serviceLayer = layer<typeof DatabaseService | typeof CacheService, typeof UserService>(
  *   (container) =>
- *     container.register(UserService, async (c) =>
- *       new UserService(await c.get(DatabaseService), await c.get(CacheService))
+ *     container.register(UserService, async (ctx) =>
+ *       new UserService(await ctx.resolve(DatabaseService), await ctx.resolve(CacheService))
  *     )
  * );
  *
  * // Compose the complete application
- * const appLayer = configLayer().to(infraLayer()).to(serviceLayer());
+ * const appLayer = serviceLayer.provide(infraLayer).provide(configLayer);
  * ```
  */
-declare function layer<TRequires extends AnyTag = never, TProvides extends AnyTag = never, TParams = undefined>(register: <TScope extends Scope>(container: IContainer<TRequires, TScope>, params: TParams) => IContainer<TRequires | TProvides, TScope>): LayerFactory<TRequires, TProvides, TParams>;
+declare function layer<TRequires extends AnyTag = never, TProvides extends AnyTag = never>(register: <TContainer extends AnyTag>(container: IContainer<TRequires | TContainer>) => IContainer<TRequires | TContainer | TProvides>): Layer<TRequires, TProvides>;
 /**
  * Helper type that extracts the union of all requirements from an array of layers.
- * Used by Layer.merge() to compute the correct requirement type for the merged layer.
+ * Used by Layer.mergeAll() to compute the correct requirement type for the merged layer.
+ *
+ * Works with AnyLayer[] constraint which accepts any concrete layer through variance:
+ * - Layer<never, X> → extracts `never` (no requirements)
+ * - Layer<A | B, Y> → extracts `A | B` (specific requirements)
  *
  * @internal
  */
-type UnionOfRequires<T extends readonly Layer<AnyTag, AnyTag>[]> = { [K in keyof T]: T[K] extends Layer<infer R, AnyTag> ? R : never }[number];
+type UnionOfRequires<T extends readonly AnyLayer[]> = { [K in keyof T]: T[K] extends Layer<infer R, any> ? R : never }[number];
 /**
  * Helper type that extracts the union of all provisions from an array of layers.
- * Used by Layer.merge() to compute the correct provision type for the merged layer.
+ * Used by Layer.mergeAll() to compute the correct provision type for the merged layer.
+ *
+ * Works with AnyLayer[] constraint which accepts any concrete layer through variance:
+ * - Layer<X, never> → extracts `never` (no provisions)
+ * - Layer<Y, A | B> → extracts `A | B` (specific provisions)
  *
  * @internal
  */
-type UnionOfProvides<T extends readonly Layer<AnyTag, AnyTag>[]> = { [K in keyof T]: T[K] extends Layer<AnyTag, infer P> ? P : never }[number];
+type UnionOfProvides<T extends readonly AnyLayer[]> = { [K in keyof T]: T[K] extends Layer<any, infer P> ? P : never }[number];
 /**
  * Utility object containing helper functions for working with layers.
  */
@@ -1092,43 +1401,58 @@ declare const Layer: {
    *
    * @example
    * ```typescript
-   * import { Layer } from 'sandl';
+   * import { Layer } from 'sandly';
    *
    * const baseLayer = Layer.empty();
    * const appLayer = baseLayer
-   *   .and(configLayer())
-   *   .and(serviceLayer());
+   *   .merge(configLayer)
+   *   .merge(serviceLayer);
    * ```
    */
-  empty(): Layer;
+  empty(): Layer<never, never>;
   /**
    * Merges multiple layers at once in a type-safe way.
-   * This is equivalent to chaining `.and()` calls but more convenient for multiple layers.
+   * This is equivalent to chaining `.merge()` calls but more convenient for multiple layers.
+   *
+   * ## Type Safety with Variance
+   *
+   * Uses the AnyLayer constraint (Layer<never, AnyTag>) which accepts any concrete layer
+   * through the Layer interface's variance annotations:
+   *
+   * - **Contravariant TRequires**: Layer<typeof ServiceA, X> can be passed because requiring
+   *   ServiceA is more restrictive than requiring `never` (nothing)
+   * - **Covariant TProvides**: Layer<Y, typeof ServiceB> can be passed because providing
+   *   ServiceB is compatible with the general `AnyTag` type
+   *
+   * The return type correctly extracts and unions the actual requirement/provision types
+   * from all input layers, preserving full type safety.
    *
    * All layers are merged in order, combining their requirements and provisions.
    * The resulting layer requires the union of all input layer requirements and
    * provides the union of all input layer provisions.
    *
-   * @template T - The tuple type of layers to merge
+   * @template T - The tuple type of layers to merge (constrained to AnyLayer for variance)
    * @param layers - At least 2 layers to merge together
-   * @returns A new layer that combines all input layers
+   * @returns A new layer that combines all input layers with correct union types
    *
-   * @example Basic usage
+   * @example Basic usage with different layer types
    * ```typescript
-   * import { Layer } from 'sandl';
+   * import { Layer } from 'sandly';
    *
-   * const infraLayer = Layer.merge(
-   *   databaseLayer(),
-   *   cacheLayer(),
-   *   loggingLayer()
-   * );
+   * // These all have different types but work thanks to variance:
+   * const dbLayer = layer<never, typeof DatabaseService>(...);           // no requirements
+   * const userLayer = layer<typeof DatabaseService, typeof UserService>(...); // requires DB
+   * const configLayer = layer<never, typeof ConfigService>(...);        // no requirements
+   *
+   * const infraLayer = Layer.mergeAll(dbLayer, userLayer, configLayer);
+   * // Type: Layer<typeof DatabaseService, typeof DatabaseService | typeof UserService | typeof ConfigService>
    * ```
    *
-   * @example Equivalent to chaining .and()
+   * @example Equivalent to chaining .merge()
    * ```typescript
    * // These are equivalent:
-   * const layer1 = Layer.merge(layerA(), layerB(), layerC());
-   * const layer2 = layerA().and(layerB()).and(layerC());
+   * const layer1 = Layer.mergeAll(layerA, layerB, layerC);
+   * const layer2 = layerA.merge(layerB).merge(layerC);
    * ```
    *
    * @example Building infrastructure layers
@@ -1138,79 +1462,211 @@ declare const Layer: {
    * const observabilityLayer = layer<never, typeof Logger | typeof Metrics>(...);
    *
    * // Merge all infrastructure concerns into one layer
-   * const infraLayer = Layer.merge(
-   *   persistenceLayer(),
-   *   messagingLayer(),
-   *   observabilityLayer()
+   * const infraLayer = Layer.mergeAll(
+   *   persistenceLayer,
+   *   messagingLayer,
+   *   observabilityLayer
    * );
    *
-   * // Now infraLayer provides: DatabaseService | CacheService | MessageQueue | Logger | Metrics
+   * // Result type: Layer<never, DatabaseService | CacheService | MessageQueue | Logger | Metrics>
    * ```
    */
-  merge<T extends readonly [Layer<AnyTag, AnyTag>, Layer<AnyTag, AnyTag>, ...Layer<AnyTag, AnyTag>[]]>(...layers: T): Layer<UnionOfRequires<T>, UnionOfProvides<T>>;
+  mergeAll<T extends readonly [AnyLayer, AnyLayer, ...AnyLayer[]]>(...layers: T): Layer<UnionOfRequires<T>, UnionOfProvides<T>>;
+  /**
+   * Merges exactly two layers, combining their requirements and provisions.
+   * This is similar to the `.merge()` method but available as a static function.
+   *
+   * @template TRequires1 - What the first layer requires
+   * @template TProvides1 - What the first layer provides
+   * @template TRequires2 - What the second layer requires
+   * @template TProvides2 - What the second layer provides
+   * @param layer1 - The first layer to merge
+   * @param layer2 - The second layer to merge
+   * @returns A new merged layer requiring both layers' requirements and providing both layers' provisions
+   *
+   * @example Merging two layers
+   * ```typescript
+   * import { Layer } from 'sandly';
+   *
+   * const dbLayer = layer<never, typeof DatabaseService>(...);
+   * const cacheLayer = layer<never, typeof CacheService>(...);
+   *
+   * const persistenceLayer = Layer.merge(dbLayer, cacheLayer);
+   * // Type: Layer<never, typeof DatabaseService | typeof CacheService>
+   * ```
+   */
+  merge<TRequires1 extends AnyTag, TProvides1 extends AnyTag, TRequires2 extends AnyTag, TProvides2 extends AnyTag>(layer1: Layer<TRequires1, TProvides1>, layer2: Layer<TRequires2, TProvides2>): Layer<TRequires1 | TRequires2, TProvides1 | TProvides2>;
 };
 //#endregion
-//#region src/service.d.ts
+//#region src/scoped-container.d.ts
+type Scope = string | symbol;
+declare class ScopedContainer<TReg extends AnyTag> extends Container<TReg> {
+  readonly scope: Scope;
+  private parent;
+  private readonly children;
+  protected constructor(parent: IContainer<TReg> | null, scope: Scope);
+  static empty(scope: Scope): ScopedContainer<never>;
+  /**
+   * Registers a dependency in the scoped container.
+   *
+   * Overrides the base implementation to return ScopedContainer type
+   * for proper method chaining support.
+   */
+  register<T extends AnyTag>(tag: T, spec: DependencySpec<T, TReg>): ScopedContainer<TReg | T>;
+  /**
+   * Checks if a dependency has been registered in this scope or any parent scope.
+   *
+   * This method checks the current scope first, then walks up the parent chain.
+   * Returns true if the dependency has been registered somewhere in the scope hierarchy.
+   */
+  has(tag: AnyTag): boolean;
+  /**
+   * Checks if a dependency has been instantiated in this scope or any parent scope.
+   *
+   * This method checks the current scope first, then walks up the parent chain.
+   * Returns true if the dependency has been instantiated somewhere in the scope hierarchy.
+   */
+  exists(tag: AnyTag): boolean;
+  /**
+   * Retrieves a dependency instance, resolving from the current scope or parent scopes.
+   *
+   * Resolution strategy:
+   * 1. Check cache in current scope
+   * 2. Check if factory exists in current scope - if so, create instance here
+   * 3. Otherwise, delegate to parent scope
+   * 4. If no parent or parent doesn't have it, throw UnknownDependencyError
+   */
+  resolve<T extends TReg>(tag: T): Promise<TagType<T>>;
+  /**
+   * Destroys this scoped container and its children, preserving the container structure for reuse.
+   *
+   * This method ensures proper cleanup order while maintaining reusability:
+   * 1. Destroys all child scopes first (they may depend on parent scope dependencies)
+   * 2. Then calls finalizers for dependencies created in this scope
+   * 3. Clears only instance caches - preserves factories, finalizers, and child structure
+   *
+   * Child destruction happens first to ensure dependencies don't get cleaned up
+   * before their dependents.
+   */
+  destroy(): Promise<void>;
+  /**
+   * Creates a new scoped container by merging this container's registrations with another container.
+   *
+   * This method overrides the base Container.merge to return a ScopedContainer instead of a regular Container.
+   * The resulting scoped container contains all registrations from both containers and becomes a root scope
+   * (no parent) with the scope name from this container.
+   *
+   * @param other - The container to merge with
+   * @returns A new ScopedContainer with combined registrations
+   * @throws {ContainerDestroyedError} If this container has been destroyed
+   */
+  merge<TTarget extends AnyTag>(other: Container<TTarget>): ScopedContainer<TReg | TTarget>;
+  /**
+   * Creates a child scoped container.
+   *
+   * Child containers inherit access to parent dependencies but maintain
+   * their own scope for new registrations and instance caching.
+   */
+  child(scope: Scope): ScopedContainer<TReg>;
+}
 /**
- * Extracts constructor parameter types from a TaggedClass.
- * Only parameters that extend AnyTag are considered as dependencies.
+ * Converts a regular container into a scoped container, copying all registrations.
+ *
+ * This function creates a new ScopedContainer instance and copies all factory functions
+ * and finalizers from the source container. The resulting scoped container becomes a root
+ * scope (no parent) with all the same dependency registrations.
+ *
+ * **Important**: Only the registrations are copied, not any cached instances.
+ * The new scoped container starts with an empty instance cache.
+ *
+ * @param container - The container to convert to a scoped container
+ * @param scope - A string or symbol identifier for this scope (used for debugging)
+ * @returns A new ScopedContainer instance with all registrations copied from the source container
+ * @throws {ContainerDestroyedError} If the source container has been destroyed
+ *
+ * @example Converting a regular container to scoped
+ * ```typescript
+ * import { container, scoped } from 'sandly';
+ *
+ * const appContainer = Container.empty()
+ *   .register(DatabaseService, () => new DatabaseService())
+ *   .register(ConfigService, () => new ConfigService());
+ *
+ * const scopedAppContainer = scoped(appContainer, 'app');
+ *
+ * // Create child scopes
+ * const requestContainer = scopedAppContainer.child('request');
+ * ```
+ *
+ * @example Copying complex registrations
+ * ```typescript
+ * const baseContainer = Container.empty()
+ *   .register(DatabaseService, () => new DatabaseService())
+ *   .register(UserService, {
+ *     factory: async (ctx) => new UserService(await ctx.resolve(DatabaseService)),
+ *     finalizer: (service) => service.cleanup()
+ *   });
+ *
+ * const scopedContainer = scoped(baseContainer, 'app');
+ * // scopedContainer now has all the same registrations with finalizers preserved
+ * ```
  */
-type ConstructorParams<T extends ClassTag<unknown>> = T extends (new (...args: infer A) => unknown) ? A : never;
+declare function scoped<TReg extends AnyTag>(container: Container<TReg>, scope: Scope): ScopedContainer<TReg>;
+//#endregion
+//#region src/service.d.ts
 /**
- * Helper to convert a tagged instance type back to its constructor type.
- * This uses the fact that tagged classes have a specific structure with TagId property.
+ * Extracts constructor parameter types from a ServiceTag.
+ * Only parameters that extend AnyTag are considered as dependencies.
+ * @internal
  */
-type InstanceToConstructorType<T> = T extends {
-  readonly [TagId]: infer Id;
-} ? Id extends string | symbol ? TaggedClass<T, Id> : never : never;
+type ConstructorParams<T extends ServiceTag<TagId, unknown>> = T extends (new (...args: infer A) => unknown) ? A : never;
 /**
- * Extracts constructor-typed dependencies from constructor parameters.
- * Converts instance types to their corresponding constructor types.
- * Handles both ClassTag dependencies (automatic) and ValueTag dependencies (via Inject helper).
+ * Extracts only dependency tags from a constructor parameter list.
+ * Filters out non‑DI parameters.
+ *
+ * Example:
+ *   [DatabaseService, Inject<typeof ConfigTag>, number]
+ *     → typeof DatabaseService | typeof ConfigTag
+ * @internal
  */
-type FilterTags<T extends readonly unknown[]> = T extends readonly [] ? never : { [K in keyof T]: T[K] extends {
-  readonly [TagId]: string | symbol;
-} ? InstanceToConstructorType<T[K]> : ExtractInjectTag<T[K]> extends never ? never : ExtractInjectTag<T[K]> }[number];
+type ExtractConstructorDeps<T extends readonly unknown[]> = T extends readonly [] ? never : { [K in keyof T]: T[K] extends {
+  readonly [ServiceTagIdKey]: infer Id;
+} ? Id extends TagId ? ServiceTag<Id, T[K]> : never : ExtractInjectTag<T[K]> extends never ? never : ExtractInjectTag<T[K]> }[number];
 /**
- * Extracts the instance type that a TaggedClass constructor creates.
+ * Produces an ordered tuple of constructor parameters
+ * where dependency parameters are replaced with their tag types,
+ * while non‑DI parameters are preserved as‑is.
+ * @internal
  */
 
 /**
- * Extracts only the dependency tags from a constructor's parameters for ClassTag services,
- * or returns never for ValueTag services (which have no constructor dependencies).
- * This is used to determine what dependencies a service requires.
+ * Union of all dependency tags a ServiceTag constructor requires.
+ * Filters out non‑DI parameters.
  */
-type ServiceDependencies<T extends AnyTag> = T extends ClassTag<unknown> ? FilterTags<ConstructorParams<T>> extends AnyTag ? FilterTags<ConstructorParams<T>> : never : never;
+type ServiceDependencies<T extends ServiceTag<TagId, unknown>> = ExtractConstructorDeps<ConstructorParams<T>> extends AnyTag ? ExtractConstructorDeps<ConstructorParams<T>> : never;
 /**
- * Represents a service layer that can be created from any tag type.
- * For ClassTag services, dependencies are automatically inferred from constructor parameters.
- * For ValueTag services, there are no dependencies since they don't have constructors.
+ * Ordered tuple of dependency tags (and other constructor params)
+ * inferred from a ServiceTag’s constructor.
  */
-interface Service<T extends AnyTag> extends Layer<ServiceDependencies<T>, T> {
-  /**
-   * The tag that this service represents (ClassTag or ValueTag)
-   */
-  readonly serviceClass: T;
-}
+
 /**
- * Creates a service layer from any tag type (ClassTag or ValueTag) with optional parameters.
+ * Creates a service layer from any tag type (ServiceTag or ValueTag) with optional parameters.
  *
- * For ClassTag services:
+ * For ServiceTag services:
  * - Dependencies are automatically inferred from constructor parameters
  * - The factory function must handle dependency injection by resolving dependencies from the container
  *
  * For ValueTag services:
  * - No constructor dependencies are needed since they don't have constructors
  *
- * @template T - The tag representing the service (ClassTag or ValueTag)
- * @template TParams - Optional parameters for service configuration
- * @param serviceClass - The tag (ClassTag or ValueTag)
- * @param factory - Factory function for service instantiation with container and optional params
- * @returns A factory function that creates a service layer
+ * @template T - The tag representing the service (ServiceTag or ValueTag)
+ * @param tag - The tag (ServiceTag or ValueTag)
+ * @param factory - Factory function for service instantiation with container
+ * @returns The service layer
  *
  * @example Simple service without dependencies
  * ```typescript
- * class LoggerService extends Tag.Class('LoggerService') {
+ * class LoggerService extends Tag.Service('LoggerService') {
  *   log(message: string) { console.log(message); }
  * }
  *
@@ -1219,11 +1675,11 @@ interface Service<T extends AnyTag> extends Layer<ServiceDependencies<T>, T> {
  *
  * @example Service with dependencies
  * ```typescript
- * class DatabaseService extends Tag.Class('DatabaseService') {
+ * class DatabaseService extends Tag.Service('DatabaseService') {
  *   query() { return []; }
  * }
  *
- * class UserService extends Tag.Class('UserService') {
+ * class UserService extends Tag.Service('UserService') {
  *   constructor(private db: DatabaseService) {
  *     super();
  *   }
@@ -1231,25 +1687,128 @@ interface Service<T extends AnyTag> extends Layer<ServiceDependencies<T>, T> {
  *   getUsers() { return this.db.query(); }
  * }
  *
- * const userService = service(UserService, async (container) =>
- *   new UserService(await container.get(DatabaseService))
+ * const userService = service(UserService, async (ctx) =>
+ *   new UserService(await ctx.resolve(DatabaseService))
  * );
  * ```
+ */
+declare function service<T extends ServiceTag<TagId, unknown>>(tag: T, spec: DependencySpec<T, ServiceDependencies<T>>): Layer<ServiceDependencies<T>, T>;
+/**
+ * Creates a service layer with automatic dependency injection by inferring constructor parameters.
+ *
+ * This is a convenience function that automatically resolves constructor dependencies and passes
+ * both DI-managed dependencies and static values to the service constructor in the correct order.
+ * It eliminates the need to manually write factory functions for services with constructor dependencies.
+ *
+ * @template T - The ServiceTag representing the service class
+ * @param tag - The service tag (must be a ServiceTag, not a ValueTag)
+ * @param deps - Tuple of constructor parameters in order - mix of dependency tags and static values
+ * @param finalizer - Optional cleanup function called when the container is destroyed
+ * @returns A service layer that automatically handles dependency injection
+ *
+ * @example Simple service with dependencies
+ * ```typescript
+ * class DatabaseService extends Tag.Service('DatabaseService') {
+ *   constructor(private url: string) {
+ *     super();
+ *   }
+ *   connect() { return `Connected to ${this.url}`; }
+ * }
+ *
+ * class UserService extends Tag.Service('UserService') {
+ *   constructor(private db: DatabaseService, private timeout: number) {
+ *     super();
+ *   }
+ *   getUsers() { return this.db.query('SELECT * FROM users'); }
+ * }
+ *
+ * // Automatically inject DatabaseService and pass static timeout value
+ * const userService = autoService(UserService, [DatabaseService, 5000]);
+ * ```
+ *
+ * @example Mixed dependencies and static values
+ * ```typescript
+ * class NotificationService extends Tag.Service('NotificationService') {
+ *   constructor(
+ *     private logger: LoggerService,
+ *     private apiKey: string,
+ *     private retries: number,
+ *     private cache: CacheService
+ *   ) {
+ *     super();
+ *   }
+ * }
+ *
+ * // Mix of DI tags and static values in constructor order
+ * const notificationService = autoService(NotificationService, [
+ *   LoggerService,    // Will be resolved from container
+ *   'secret-api-key', // Static string value
+ *   3,                // Static number value
+ *   CacheService      // Will be resolved from container
+ * ]);
+ * ```
+ *
+ * @example Compared to manual service creation
+ * ```typescript
+ * // Manual approach (more verbose)
+ * const userServiceManual = service(UserService, async (ctx) => {
+ *   const db = await ctx.resolve(DatabaseService);
+ *   return new UserService(db, 5000);
+ * });
+ *
+ * // Auto approach (concise)
+ * const userServiceAuto = autoService(UserService, [DatabaseService, 5000]);
+ * ```
  *
- * @example Service with configuration parameters
+ * @example With finalizer for cleanup
  * ```typescript
- * class DatabaseService extends Tag.Class('DatabaseService') {
- *   constructor(private config: { dbUrl: string }) {
+ * class DatabaseService extends Tag.Service('DatabaseService') {
+ *   constructor(private connectionString: string) {
  *     super();
  *   }
+ *
+ *   private connection: Connection | null = null;
+ *
+ *   async connect() {
+ *     this.connection = await createConnection(this.connectionString);
+ *   }
+ *
+ *   async disconnect() {
+ *     if (this.connection) {
+ *       await this.connection.close();
+ *       this.connection = null;
+ *     }
+ *   }
  * }
  *
- * const dbService = service(
+ * // Service with automatic cleanup
+ * const dbService = autoService(
  *   DatabaseService,
- *   (container, params: { dbUrl: string }) => new DatabaseService(params)
+ *   ['postgresql://localhost:5432/mydb'],
+ *   (service) => service.disconnect() // Finalizer for cleanup
  * );
  * ```
  */
-declare function service<T extends AnyTag, TParams = undefined>(serviceClass: T, factory: (container: IContainer<ServiceDependencies<T>>, params: TParams) => PromiseOrValue<ServiceOf<T>>): TParams extends undefined ? () => Service<T> : (params: TParams) => Service<T>;
 //#endregion
-export { type Inject, Layer, type Scope, type Service, type ServiceOf, Tag, type TaggedClass, type ValueTag, container, layer, scopedContainer, service };
+//#region src/value.d.ts
+/**
+ * Creates a layer that provides a constant value for a given tag.
+ *
+ * @param tag - The value tag to provide
+ * @param constantValue - The constant value to provide
+ * @returns A layer with no dependencies that provides the constant value
+ *
+ * @example
+ * ```typescript
+ * const ApiKey = Tag.of('ApiKey')<string>();
+ * const DatabaseUrl = Tag.of('DatabaseUrl')<string>();
+ *
+ * const apiKey = value(ApiKey, 'my-secret-key');
+ * const dbUrl = value(DatabaseUrl, 'postgresql://localhost:5432/myapp');
+ *
+ * const config = Layer.merge(apiKey, dbUrl);
+ * ```
+ */
+declare function value<Id extends TagId, T>(tag: ValueTag<Id, T>, constantValue: T): Layer<never, ValueTag<Id, T>>;
+//#endregion
+export { type AnyLayer, type AnyTag, CircularDependencyError, Container, ContainerDestroyedError, ContainerError, DependencyAlreadyInstantiatedError, DependencyCreationError, DependencyFinalizationError, type DependencyLifecycle, type DependencySpec, type Factory, type Finalizer, type IContainer, type Inject, InjectSource, Layer, type PromiseOrValue, type ResolutionContext, type Scope, ScopedContainer, type ServiceTag, Tag, type TagType, UnknownDependencyError, type ValueTag, layer, scoped, service, value };