sandly 0.0.2 → 0.1.0

package/dist/index.d.ts

@@ -1,4 +1,44 @@
 //#region src/tag.d.ts
+/**
+ * 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.
+ *
+ * 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;
 /**
  * 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.
@@ -24,11 +64,11 @@ declare const TagId: "__tag_id__";
  * container.register(ApiKeyTag, () => 'my-secret-key');
  * ```
  */
-type ValueTag<T, Id extends string | symbol> = Readonly<{
+interface ValueTag<T, Id extends string | symbol> {
   readonly [TagId]: Id;
   /** @internal Phantom type to carry T */
   readonly __type: T;
-}>;
+}
 /**
  * Type representing a class-based dependency tag.
  *
@@ -52,23 +92,51 @@ type ValueTag<T, Id extends string | symbol> = Readonly<{
  *
  * @internal - Users should use Tag.Class() instead of working with this type directly
  */
-type TaggedClass<T, Id extends string | symbol> = {
+interface ClassTag<T, Id extends string | symbol> {
   new (...args: any[]): T & {
     readonly [TagId]: Id;
   };
   readonly [TagId]: 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 ClassTag)
+ * @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 }>();
  *
- * @internal - Users should use Tag.Class() instead of working with this type directly
+ * type StringService = TagType<typeof StringTag>; // string
+ * type ConfigService = TagType<typeof ConfigTag>; // { apiKey: string }
+ * ```
+ *
+ * @example With class tags
+ * ```typescript
+ * class UserService extends Tag.Class('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
+ *
+ * const str: string = await container.get(StringTag); // Automatically typed as string
+ * const user: UserService = await container.get(UserService); // Automatically typed as UserService
+ * ```
  */
-type ClassTag<T> = TaggedClass<T, string | symbol>;
+type TagType<T> = T extends ValueTag<infer V, string | symbol> ? V : T extends ClassTag<infer V, string | symbol> ? V : never;
 /**
  * Union type representing any valid dependency tag in the system.
  *
@@ -88,7 +156,7 @@ type ClassTag<T> = TaggedClass<T, string | symbol>;
  * // DatabaseService satisfies AnyTag
  * ```
  */
-type AnyTag = ValueTag<any, string | symbol> | TaggedClass<any, string | symbol>;
+type AnyTag = ValueTag<any, string | symbol> | ClassTag<any, string | symbol>;
 /**
  * Utility object containing factory functions for creating dependency tags.
  *
@@ -227,8 +295,8 @@ 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.get(DatabaseService))
    *   );
    * ```
    *
@@ -241,9 +309,7 @@ declare const Tag: {
    * }
    * ```
    */
-  Class: <Id extends string | symbol>(id: Id) => TaggedClass<{
-    /** @internal */
-    readonly __type: unknown;
+  Class: <Id extends string | symbol>(id: Id) => ClassTag<{
     readonly __tag_id__: Id;
   }, Id>;
   /**
@@ -271,63 +337,11 @@ declare const Tag: {
    */
   id: (tag: AnyTag) => string;
 };
-/**
- * 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.
- *
- * @template T - Any dependency tag (ValueTag or TaggedClass)
- * @returns The service type that the tag represents
- *
- * @example With value tags
- * ```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 }
- * ```
- *
- * @example With class tags
- * ```typescript
- * class UserService extends Tag.Class('UserService') {
- *   getUsers() { return []; }
- * }
- *
- * 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;
-/**
- * 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
- * @internal
- */
-
+//#endregion
+//#region src/container.d.ts
 /**
  * Type representing a factory function used to create dependency instances.
  *
@@ -343,58 +357,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.get(ConfigTag),
+ *     ctx.get(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 +415,90 @@ 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.Class('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().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().register(UserService, spec);
+ * ```
+ *
+ * @example Lifecycle registration
+ * ```typescript
+ * const spec: DependencySpec<typeof DatabaseConnection, never> = {
+ *   factory: () => new DatabaseConnection(),
+ *   finalizer: (conn) => conn.close()
+ * };
+ *
+ * container().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 `get` method from the container, which is 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>, 'get'>;
+/**
+ * Interface representing a container that can register and retrieve dependencies.
+ *
+ * @template TReg - Union type of all dependencies available in the container
+ */
+interface IContainer<in TReg extends AnyTag> {
+  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;
+  get<T extends TReg>(tag: T): Promise<TagType<T>>;
+  merge<TTarget extends AnyTag>(other: IContainer<TTarget>): IContainer<TReg | TTarget>;
   destroy(): Promise<void>;
 }
 /**
@@ -464,7 +514,7 @@ interface IContainer<TReg extends AnyTag, TScope extends Scope = DefaultScope> {
  *
  * @example Basic usage with class tags
  * ```typescript
- * import { container, Tag } from 'sandl';
+ * import { container, Tag } from 'sandly';
  *
  * class DatabaseService extends Tag.Class('DatabaseService') {
  *   query() { return 'data'; }
@@ -477,8 +527,8 @@ interface IContainer<TReg extends AnyTag, TScope extends Scope = DefaultScope> {
  *
  * const c = container()
  *   .register(DatabaseService, () => new DatabaseService())
- *   .register(UserService, async (container) =>
- *     new UserService(await container.get(DatabaseService))
+ *   .register(UserService, async (ctx) =>
+ *     new UserService(await ctx.get(DatabaseService))
  *   );
  *
  * const userService = await c.get(UserService);
@@ -518,23 +568,28 @@ interface IContainer<TReg extends AnyTag, TScope extends Scope = DefaultScope> {
  * await c.destroy(); // Calls all finalizers
  * ```
  */
-declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
+declare class Container<in TReg extends AnyTag = never> implements IContainer<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;
   /**
    * Registers a dependency in the container with a factory function and optional finalizer.
    *
@@ -542,12 +597,16 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * service instance (or a Promise of it). The container tracks the registration at
    * the type level, ensuring type safety for subsequent `.get()` 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
@@ -570,14 +629,21 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * const c = container()
    *   .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.get(DatabaseService),
+   *       await ctx.get(LoggerService)
    *     )
    *   );
    * ```
    *
+   * @example Overriding a dependency
+   * ```typescript
+   * const c = container()
+   *   .register(DatabaseService, () => new DatabaseService())
+   *   .register(DatabaseService, () => new MockDatabaseService()); // Overrides the previous registration
+   * ```
+   *
    * @example Using value tags
    * ```typescript
    * const ConfigTag = Tag.of('config')<{ apiUrl: string }>();
@@ -606,27 +672,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
+   * 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.
    *
@@ -669,21 +738,56 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * ```typescript
    * const c = container()
    *   .register(DatabaseService, () => new DatabaseService())
-   *   .register(UserService, async (container) => {
-   *     const db = await container.get(DatabaseService);
+   *   .register(UserService, async (ctx) => {
+   *     const db = await ctx.get(DatabaseService);
    *     return new UserService(db);
    *   });
    *
    * const userService = await c.get(UserService);
    * ```
    */
-  get<T extends TReg>(tag: T): Promise<ServiceOf<T>>;
+  get<T extends TReg>(tag: T): Promise<TagType<T>>;
+  /**
+   * 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()
+   *   .register(DatabaseService, () => new DatabaseService());
+   *
+   * const container2 = container()
+   *   .register(UserService, () => new UserService());
+   *
+   * const merged = container1.merge(container2);
+   * // merged has both DatabaseService and UserService
+   * ```
+   */
+  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,9 +799,9 @@ 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()
    *   .register(DatabaseConnection,
@@ -709,24 +813,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.get(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.get(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()
+   *   .register(DatabaseService, () => new DatabaseService())
+   *   .register(HTTPServer, async (ctx) => new HTTPServer(await ctx.get(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,96 +850,11 @@ 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;
-  /**
-   * 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
-   */
-  get<T extends TReg>(tag: T): Promise<ServiceOf<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 child scoped container.
-   *
-   * Child containers inherit access to parent dependencies but maintain
-   * their own scope for new registrations and instance caching.
-   */
-  child<TChildScope extends Scope>(scope: TChildScope): ScopedContainer<TReg, TScope | TChildScope>;
-}
 /**
  * Creates a new empty dependency injection container.
  *
@@ -839,35 +866,254 @@ declare class ScopedContainer<TReg extends AnyTag, TScope extends Scope> impleme
  *
  * @example
  * ```typescript
- * import { container, Tag } from 'sandl';
+ * import { container, Tag } from 'sandly';
  *
  * 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))
+ *   .register(UserService, async (ctx) =>
+ *     new UserService(await ctx.get(DatabaseService))
  *   );
  *
  * const userService = await c.get(UserService);
  * ```
  */
-declare function container(): Container<never>;
-declare function scopedContainer<TScope extends Scope>(scope: TScope): ScopedContainer<never, TScope>;
+declare function container(): Container;
+//#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.get(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.get()`, `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.get(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 container
+ *
+ * try {
+ *   await c.get(UnregisteredService); // This will throw
+ * } catch (error) {
+ *   if (error instanceof UnknownDependencyError) {
+ *     console.error('Missing dependency:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class UnknownDependencyError extends ContainerError {
+  /**
+   * @internal
+   * Creates an UnknownDependencyError for the given tag.
+   *
+   * @param tag - The dependency tag that wasn't found
+   */
+  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.Class('ServiceA') {}
+ * class ServiceB extends Tag.Class('ServiceB') {}
+ *
+ * const c = container()
+ *   .register(ServiceA, async (ctx) =>
+ *     new ServiceA(await ctx.get(ServiceB)) // Depends on B
+ *   )
+ *   .register(ServiceB, async (ctx) =>
+ *     new ServiceB(await ctx.get(ServiceA)) // Depends on A - CIRCULAR!
+ *   );
+ *
+ * try {
+ *   await c.get(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 {
+  /**
+   * @internal
+   * Creates a CircularDependencyError with the dependency chain information.
+   *
+   * @param tag - The tag where the circular dependency was detected
+   * @param dependencyChain - The chain of dependencies that led to the circular reference
+   */
+  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.Class('DatabaseService') {}
+ *
+ * const c = container().register(DatabaseService, () => {
+ *   throw new Error('Database connection failed');
+ * });
+ *
+ * try {
+ *   await c.get(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 {
+  /**
+   * @internal
+   * Creates a DependencyCreationError wrapping the original factory error.
+   *
+   * @param tag - The tag of the dependency that failed to be created
+   * @param error - The original error thrown by the factory function
+   */
+  constructor(tag: AnyTag, error: unknown);
+}
+/**
+ * Error thrown when one or more finalizers fail during container destruction.
+ *
+ * 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.
+ *
+ * @example Handling finalization errors
+ * ```typescript
+ * try {
+ *   await container.destroy();
+ * } catch (error) {
+ *   if (error instanceof DependencyFinalizationError) {
+ *     console.error('Some finalizers failed');
+ *     console.error('Error details:', error.detail.errors);
+ *   }
+ * }
+ * ```
+ */
+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 works with variance - accepts any concrete layer.
+ *
+ * This type is carefully constructed to work with the Layer interface's variance annotations:
+ * - `never` for TRequires (contravariant): Any layer requiring specific dependencies can be
+ *   assigned to this since requiring something is more restrictive than requiring nothing
+ * - `AnyTag` for TProvides (covariant): Any layer providing specific services can be assigned
+ *   to this since the general AnyTag type can represent any specific tag type
+ *
+ * Used internally for functions like Layer.mergeAll() that need to accept arrays of layers
+ * with different requirement/provision types while preserving type safety through variance.
+ */
+type AnyLayer = Layer<never, AnyTag>;
 /**
  * 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 (contravariant with `in`)
+ * 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 (covariant with `out`)
+ * 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') {
  *   query() { return 'data'; }
@@ -880,69 +1126,124 @@ declare function scopedContainer<TScope extends Scope>(scope: TScope): ScopedCon
  *
  * // Apply the layer to a container
  * const c = container();
- * const finalContainer = databaseLayer().register(c);
+ * const finalContainer = databaseLayer.register(c);
  *
  * const db = await finalContainer.get(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.get(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);
+ *
+ * // Thanks to variance, Layer<never, typeof DatabaseService> automatically works
+ * // where Layer<typeof DatabaseService, typeof UserService> requires DatabaseService
  * ```
  */
-interface Layer<TRequires extends AnyTag = never, TProvides extends AnyTag = never> {
+interface Layer<in TRequires extends AnyTag = never, out TProvides extends AnyTag = never> {
   /**
    * 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();
+   * const updatedContainer = myLayer.register(c);
+   * ```
+   *
+   * @example With existing services preserved
+   * ```typescript
+   * const baseContainer = container()
+   *   .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
+   * @example Multi-level composition (reads naturally left-to-right)
    * ```typescript
-   * const appLayer = configLayer()
-   *   .to(databaseLayer())
-   *   .to(serviceLayer())
-   *   .to(apiLayer());
+   * 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 Difference from .provide()
+   * ```typescript
+   * // .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,40 +1260,31 @@ 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') {
  *   constructor(private url: string = 'sqlite://memory') {}
@@ -1005,37 +1297,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 +1311,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.get(ConfigTag)))
+ *       .register(CacheService, async (ctx) => new CacheService(await ctx.get(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.get(DatabaseService), await ctx.get(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, AnyTag> ? 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<never, infer P> ? P : never }[number];
 /**
  * Utility object containing helper functions for working with layers.
  */
@@ -1092,43 +1362,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;
   /**
    * 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,31 +1423,169 @@ 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/scoped-container.d.ts
+type Scope = string | symbol;
+declare class ScopedContainer<in TReg extends AnyTag = never> extends Container<TReg> {
+  readonly scope: Scope;
+  private parent;
+  private readonly children;
+  constructor(parent: IContainer<TReg> | null, scope: Scope);
+  /**
+   * 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
+   */
+  get<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>;
+}
+/**
+ * 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()
+ *   .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()
+ *   .register(DatabaseService, () => new DatabaseService())
+ *   .register(UserService, {
+ *     factory: async (ctx) => new UserService(await ctx.get(DatabaseService)),
+ *     finalizer: (service) => service.cleanup()
+ *   });
+ *
+ * const scopedContainer = scoped(baseContainer, 'app');
+ * // scopedContainer now has all the same registrations with finalizers preserved
+ * ```
+ */
+declare function scoped<TReg extends AnyTag>(container: Container<TReg>, scope: Scope): ScopedContainer<TReg>;
+//#endregion
 //#region src/service.d.ts
 /**
- * Extracts constructor parameter types from a TaggedClass.
+ * Extracts constructor parameter types from a ClassTag.
  * Only parameters that extend AnyTag are considered as dependencies.
  */
-type ConstructorParams<T extends ClassTag<unknown>> = T extends (new (...args: infer A) => unknown) ? A : never;
+type ConstructorParams<T extends ClassTag<unknown, string | symbol>> = T extends (new (...args: infer A) => unknown) ? A : never;
 /**
  * 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.
  */
 type InstanceToConstructorType<T> = T extends {
   readonly [TagId]: infer Id;
-} ? Id extends string | symbol ? TaggedClass<T, Id> : never : never;
+} ? Id extends string | symbol ? ClassTag<T, Id> : never : never;
 /**
  * Extracts constructor-typed dependencies from constructor parameters.
  * Converts instance types to their corresponding constructor types.
@@ -1171,27 +1594,12 @@ type InstanceToConstructorType<T> = T extends {
 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];
-/**
- * Extracts the instance type that a TaggedClass constructor creates.
- */
-
 /**
  * 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.
  */
-type ServiceDependencies<T extends AnyTag> = T extends ClassTag<unknown> ? FilterTags<ConstructorParams<T>> extends AnyTag ? FilterTags<ConstructorParams<T>> : never : 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.
- */
-interface Service<T extends AnyTag> extends Layer<ServiceDependencies<T>, T> {
-  /**
-   * The tag that this service represents (ClassTag or ValueTag)
-   */
-  readonly serviceClass: T;
-}
+type ServiceDependencies<T extends AnyTag> = T extends ClassTag<unknown, string | symbol> ? FilterTags<ConstructorParams<T>> extends AnyTag ? FilterTags<ConstructorParams<T>> : never : never;
 /**
  * Creates a service layer from any tag type (ClassTag or ValueTag) with optional parameters.
  *
@@ -1203,10 +1611,9 @@ interface Service<T extends AnyTag> extends Layer<ServiceDependencies<T>, T> {
  * - 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
+ * @param factory - Factory function for service instantiation with container
+ * @returns The service layer
  *
  * @example Simple service without dependencies
  * ```typescript
@@ -1231,25 +1638,32 @@ 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.get(DatabaseService))
  * );
  * ```
+ */
+declare function service<T extends AnyTag>(serviceClass: T, spec: DependencySpec<T, ServiceDependencies<T>>): Layer<ServiceDependencies<T>, T>;
+//#endregion
+//#region src/value.d.ts
+/**
+ * Creates a layer that provides a constant value for a given tag.
  *
- * @example Service with configuration parameters
+ * @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
- * class DatabaseService extends Tag.Class('DatabaseService') {
- *   constructor(private config: { dbUrl: string }) {
- *     super();
- *   }
- * }
+ * const ApiKey = Tag.of('ApiKey')<string>();
+ * const DatabaseUrl = Tag.of('DatabaseUrl')<string>();
  *
- * const dbService = service(
- *   DatabaseService,
- *   (container, params: { dbUrl: string }) => new DatabaseService(params)
- * );
+ * const apiKey = value(ApiKey, 'my-secret-key');
+ * const dbUrl = value(DatabaseUrl, 'postgresql://localhost:5432/myapp');
+ *
+ * const config = Layer.merge(apiKey, dbUrl);
  * ```
  */
-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>;
+declare function value<T, Id extends string | symbol>(tag: ValueTag<T, Id>, constantValue: T): Layer<never, ValueTag<T, Id>>;
 //#endregion
-export { type Inject, Layer, type Scope, type Service, type ServiceOf, Tag, type TaggedClass, type ValueTag, container, layer, scopedContainer, service };
+export { type AnyLayer, type AnyTag, CircularDependencyError, type ClassTag, Container, ContainerDestroyedError, ContainerError, DependencyAlreadyInstantiatedError, DependencyCreationError, DependencyFinalizationError, type DependencyLifecycle, type Factory, type Finalizer, type IContainer, type Inject, Layer, type PromiseOrValue, type ResolutionContext, type Scope, ScopedContainer, Tag, type TagType, UnknownDependencyError, type ValueTag, container, layer, scoped, service, value };