sandly 1.0.0 → 2.0.0

package/dist/index.d.ts

@@ -1,1510 +1,882 @@
 //#region src/tag.d.ts
 /**
  * Type representing a tag identifier (string or symbol).
- * @internal
  */
 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'.
- *
+ * Symbol used to identify ValueTag objects at runtime.
  * @internal
  */
 declare const ValueTagIdKey = "sandly/ValueTagIdKey";
-declare const ServiceTagIdKey = "sandly/ServiceTagIdKey";
 /**
- * Internal string used to identify the type of a tagged type within the dependency injection system.
- * This string 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.
+ * Symbol used to carry the phantom type for ValueTag.
  * @internal
  */
 declare const TagTypeKey = "sandly/TagTypeKey";
 /**
- * Type representing a value-based dependency tag.
+ * A ServiceTag is any class constructor.
  *
- * Value tags are used to represent non-class dependencies like configuration objects,
- * strings, numbers, or any other values. They use phantom types to maintain type safety
- * while being distinguishable at runtime through their unique identifiers.
+ * Any class can be used directly as a dependency tag without special markers.
  *
- * @template T - The type of the value this tag represents
- * @template Id - The unique identifier for this tag (string or symbol)
+ * @template T - The type of instances created by this class
  *
  * @example
  * ```typescript
- * // Creates a value tag for string configuration
- * const ApiKeyTag: ValueTag<'apiKey', string> = Tag.of('apiKey')<string>();
+ * class UserService {
+ *   constructor(private db: Database) {}
+ *   getUsers() { return this.db.query('SELECT * FROM users'); }
+ * }
  *
- * // Register in container
- * container.register(ApiKeyTag, () => 'my-secret-key');
+ * const container = Container.builder()
+ *   .add(UserService, ...)
+ *   .build();
  * ```
  */
-interface ValueTag<Id extends TagId, T> {
-  readonly [ValueTagIdKey]: Id;
-  readonly [TagTypeKey]: T;
-}
+type ServiceTag<T = unknown> = new (...args: any[]) => T;
 /**
- * Type representing a class-based dependency tag.
+ * A ValueTag represents a non-class dependency (primitives, objects, functions).
  *
- * 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.
+ * ValueTags use phantom types to maintain type safety while being
+ * distinguishable at runtime through their unique identifiers.
  *
  * @template Id - The unique identifier for this tag (string or symbol)
- * @template T - The type of instances created by this tagged class
+ * @template T - The type of the value this tag represents
  *
  * @example
  * ```typescript
- * // Creates a tagged class
- * class UserService extends Tag.Service('UserService') {
- *   getUsers() { return []; }
- * }
+ * const ApiKeyTag = Tag.of('ApiKey')<string>();
+ * const ConfigTag = Tag.of('Config')<{ dbUrl: string }>();
  *
- * // Register in container
- * container.register(UserService, () => new UserService());
+ * const container = Container.builder()
+ *   .add(ApiKeyTag, () => process.env.API_KEY!)
+ *   .add(ConfigTag, () => ({ dbUrl: 'postgres://...' }))
+ *   .build();
  * ```
- *
- * @internal - Users should use Tag.Service() instead of working with this type directly
  */
-interface ServiceTag<Id extends TagId, T> {
-  new (...args: any[]): T & {
-    readonly [ServiceTagIdKey]?: Id;
-  };
-  readonly [ServiceTagIdKey]?: Id;
+interface ValueTag<Id extends TagId, T> {
+  readonly [ValueTagIdKey]: Id;
+  readonly [TagTypeKey]: T;
 }
 /**
- * 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 ServiceTag)
- * @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 = 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
+ * Union type representing any valid dependency tag in the system.
  *
- * const str: string = await container.resolve(StringTag); // Automatically typed as string
- * const user: UserService = await container.resolve(UserService); // Automatically typed as UserService
- * ```
+ * A tag can be either:
+ * - A class constructor (ServiceTag) - for class-based dependencies
+ * - A ValueTag - for non-class dependencies (primitives, objects, functions)
  */
-type TagType<TTag extends AnyTag> = TTag extends ValueTag<any, infer T> ? T : TTag extends ServiceTag<any, infer T> ? T : never;
+type AnyTag = ServiceTag | ValueTag<TagId, any>;
 /**
- * Union type representing any valid dependency tag in the system.
+ * Extracts the instance/value type from any dependency tag.
  *
- * A tag can be either a value tag (for non-class dependencies) or a tagged class
- * (for service classes). This type is used throughout the DI system to constrain
- * what can be used as a dependency identifier.
+ * - For ServiceTag (class): extracts the instance type
+ * - For ValueTag: extracts the value type
  *
- * @example Value tag
+ * @example
  * ```typescript
- * const ConfigTag = Tag.of('config')<{ apiUrl: string }>();
- * // ConfigTag satisfies AnyTag
- * ```
+ * class UserService { ... }
+ * const ConfigTag = Tag.of('Config')<{ url: string }>();
  *
- * @example Class tag
- * ```typescript
- * class DatabaseService extends Tag.Service('DatabaseService') {}
- * // DatabaseService satisfies AnyTag
+ * type A = TagType<typeof UserService>;  // UserService
+ * type B = TagType<typeof ConfigTag>;    // { url: string }
  * ```
  */
-type AnyTag = ValueTag<TagId, any> | ServiceTag<TagId, any>;
+type TagType<T extends AnyTag> = T extends (new (...args: any[]) => infer Instance) ? Instance : T extends ValueTag<any, infer Value> ? Value : never;
 /**
- * Utility object containing factory functions for creating dependency 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.
+ * Utility object for creating and working with tags.
  */
 declare const Tag: {
   /**
-   * Creates a value tag factory for dependencies that are not classes.
+   * Creates a ValueTag factory for non-class dependencies.
    *
-   * This method returns a factory function that, when called with a type parameter,
-   * creates a value tag for that type. The tag has a string or symbol-based identifier
-   * that must be unique within your application.
+   * @param id - The unique identifier for this tag (string or symbol)
+   * @returns A factory function that creates a ValueTag for the specified type
    *
-   * @template Id - The string or symbol identifier for this tag (must be unique)
-   * @param id - The unique string or symbol identifier for this tag
-   * @returns A factory function that creates value tags for the specified type
-   *
-   * @example Basic usage with strings
+   * @example
    * ```typescript
-   * const ApiKeyTag = Tag.of('apiKey')<string>();
-   * const ConfigTag = Tag.of('config')<{ dbUrl: string; port: number }>();
-   *
-   * container
-   *   .register(ApiKeyTag, () => process.env.API_KEY!)
-   *   .register(ConfigTag, () => ({ dbUrl: 'postgresql://localhost', port: 5432 }));
+   * const ApiKeyTag = Tag.of('ApiKey')<string>();
+   * const PortTag = Tag.of('Port')<number>();
+   * const ConfigTag = Tag.of('Config')<{ dbUrl: string; port: number }>();
    * ```
+   */
+  of: <Id extends TagId>(id: Id) => <T>() => ValueTag<Id, T>;
+  /**
+   * Gets a string identifier for any tag, used for error messages.
+   *
+   * For classes: uses static `Tag` property if present, otherwise `constructor.name`
+   * For ValueTags: uses the tag's id
    *
-   * @example Usage with symbols
+   * @example
    * ```typescript
-   * const DB_CONFIG_SYM = Symbol('database-config');
-   * const ConfigTag = Tag.of(DB_CONFIG_SYM)<DatabaseConfig>();
+   * class UserService {}
+   * Tag.id(UserService);  // "UserService"
+   *
+   * class ApiClient {
+   *   static readonly Tag = 'MyApiClient';  // Custom name
+   * }
+   * Tag.id(ApiClient);  // "MyApiClient"
    *
-   * container.register(ConfigTag, () => ({ host: 'localhost', port: 5432 }));
+   * const ConfigTag = Tag.of('app.config')<Config>();
+   * Tag.id(ConfigTag);  // "app.config"
    * ```
+   */
+  id: (tag: AnyTag) => string;
+  /**
+   * Type guard to check if a value is a ServiceTag (class constructor).
    *
-   * @example Primitive values
-   * ```typescript
-   * const PortTag = Tag.of('port')<number>();
-   * const EnabledTag = Tag.of('enabled')<boolean>();
+   * Returns true for class declarations, class expressions, and regular functions
+   * (which can be used as constructors in JavaScript).
    *
-   * container
-   *   .register(PortTag, () => 3000)
-   *   .register(EnabledTag, () => true);
+   * Returns false for arrow functions since they cannot be used with `new`.
+   */
+  isServiceTag: (x: unknown) => x is ServiceTag;
+  /**
+   * Type guard to check if a value is a ValueTag.
+   */
+  isValueTag: (x: unknown) => x is ValueTag<TagId, any>;
+  /**
+   * Type guard to check if a value is any kind of tag (ServiceTag or ValueTag).
+   */
+  isTag: (x: unknown) => x is AnyTag;
+}; //#endregion
+//#region src/types.d.ts
+/**
+ * Type representing a value that can be either synchronous or a Promise.
+ * Used throughout the DI system to support both sync and async factories/finalizers.
+ */
+type PromiseOrValue<T> = T | Promise<T>;
+/**
+ * Variance marker types for type-level programming.
+ * Used to control how generic types behave with respect to subtyping.
+ */
+type Contravariant<A> = (_: A) => void;
+type Covariant<A> = (_: never) => A;
+
+//#endregion
+//#region src/layer.d.ts
+/**
+ * Replaces the TTags type parameter in a builder type with a new type.
+ * Preserves the concrete builder type (ContainerBuilder or ScopedContainerBuilder).
+ * @internal
+ */
+type WithBuilderTags<TBuilder, TNewTags extends AnyTag> = TBuilder extends ScopedContainerBuilder ? ScopedContainerBuilder<TNewTags> : TBuilder extends ContainerBuilder ? ContainerBuilder<TNewTags> : IContainerBuilder<TNewTags>;
+/**
+ * Defines what constitutes a valid dependency for a given parameter type T.
+ * A valid dependency is either:
+ * - A ServiceTag (class) whose instances are assignable to T
+ * - A ValueTag whose value type is assignable to T
+ * - A raw value of type T
+ * @internal
+ */
+type ValidDepFor<T> = (T extends object ? ServiceTag<T> | ValueTag<any, T> : ValueTag<any, T>) | T;
+/**
+ * Maps constructor parameters to valid dependency types.
+ * Each parameter type T becomes ValidDepFor<T>.
+ * @internal
+ */
+type ValidDepsFor<TParams extends readonly unknown[]> = { readonly [K in keyof TParams]: ValidDepFor<TParams[K]> };
+/**
+ * Extracts only the tags from a dependency array (filters out raw values).
+ * Used to determine layer requirements.
+ * @internal
+ */
+type ExtractTags<T extends readonly unknown[]> = { [K in keyof T]: T[K] extends AnyTag ? T[K] : never }[number];
+/**
+ * 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;
+/**
+ * Helper type that extracts the union of all requirements from an array of layers.
+ * @internal
+ */
+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.
+ * @internal
+ */
+type UnionOfProvides<T extends readonly AnyLayer[]> = { [K in keyof T]: T[K] extends Layer<any, infer P> ? P : never }[number];
+/**
+ * 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
+ *
+ * - **TRequires (covariant)**: A layer requiring fewer dependencies can substitute one requiring more
+ * - **TProvides (contravariant)**: A layer providing more services can substitute one providing fewer
+ *
+ * @template TRequires - The union of tags this layer requires
+ * @template TProvides - The union of tags this layer provides
+ *
+ * @example
+ * ```typescript
+ * // Create layers using Layer.service(), Layer.value(), or Layer.create()
+ * const dbLayer = Layer.service(Database, []);
+ * const userLayer = Layer.service(UserService, [Database]);
+ *
+ * // Compose layers
+ * const appLayer = userLayer.provide(dbLayer);
+ *
+ * // Create container from layer
+ * const container = Container.from(appLayer);
+ * ```
+ */
+interface Layer<TRequires extends AnyTag, TProvides extends AnyTag> {
+  readonly [LayerTypeId]?: {
+    readonly _TRequires: Covariant<TRequires>;
+    readonly _TProvides: Contravariant<TProvides>;
+  };
+  /**
+   * Applies this layer's registrations to a container builder.
+   * Works with both ContainerBuilder and ScopedContainerBuilder.
+   * @internal
+   */
+  apply: <TBuilder extends IContainerBuilder<TRequires>>(builder: TBuilder) => WithBuilderTags<TBuilder, TRequires | TProvides>;
+  /**
+   * Provides a dependency layer to this layer, creating a pipeline.
+   * The result only exposes this layer's provisions (not the dependency's).
+   *
+   * @example
+   * ```typescript
+   * const appLayer = apiLayer
+   *   .provide(serviceLayer)
+   *   .provide(databaseLayer);
    * ```
+   */
+  provide: <TDepRequires extends AnyTag, TDepProvides extends AnyTag>(dependency: Layer<TDepRequires, TDepProvides>) => Layer<TDepRequires | Exclude<TRequires, TDepProvides>, TProvides>;
+  /**
+   * Provides a dependency layer and merges both layers' provisions.
+   * Unlike `.provide()`, this exposes both this layer's and the dependency's provisions.
    *
-   * @example Complex objects
+   * @example
    * ```typescript
-   * interface DatabaseConfig {
-   *   host: string;
-   *   port: number;
-   *   database: string;
-   * }
+   * const infraLayer = dbLayer.provideMerge(configLayer);
+   * // Provides both Database and Config
+   * ```
+   */
+  provideMerge: <TDepRequires extends AnyTag, TDepProvides extends AnyTag>(dependency: Layer<TDepRequires, TDepProvides>) => Layer<TDepRequires | Exclude<TRequires, TDepProvides>, TProvides | TDepProvides>;
+  /**
+   * Merges this layer with another independent layer.
+   * Combines their requirements and provisions.
    *
-   * const DbConfigTag = Tag.of('database-config')<DatabaseConfig>();
-   * container.register(DbConfigTag, () => ({
-   *   host: 'localhost',
-   *   port: 5432,
-   *   database: 'myapp'
-   * }));
+   * @example
+   * ```typescript
+   * const infraLayer = persistenceLayer.merge(loggingLayer);
    * ```
    */
-  of: <Id extends TagId>(id: Id) => <T>() => ValueTag<Id, T>;
+  merge: <TOtherRequires extends AnyTag, TOtherProvides extends AnyTag>(other: Layer<TOtherRequires, TOtherProvides>) => Layer<TRequires | TOtherRequires, TProvides | TOtherProvides>;
+}
+/**
+ * Consolidated Layer API for creating and composing dependency layers.
+ *
+ * @example
+ * ```typescript
+ * // Define services
+ * class Database {
+ *   query(sql: string) { return []; }
+ * }
+ *
+ * class UserService {
+ *   constructor(private db: Database) {}
+ *   getUsers() { return this.db.query('SELECT * FROM users'); }
+ * }
+ *
+ * // Create layers
+ * const dbLayer = Layer.service(Database, []);
+ * const userLayer = Layer.service(UserService, [Database]);
+ *
+ * // Compose and create container
+ * const appLayer = userLayer.provide(dbLayer);
+ * const container = Container.from(appLayer);
+ *
+ * const users = await container.resolve(UserService);
+ * ```
+ */
+declare const Layer: {
   /**
-   * Creates a base class that can be extended to create service classes with dependency tags.
+   * Creates a layer that provides a class service with automatic dependency injection.
    *
-   * This is the primary way to define service classes in the dependency injection system.
-   * Classes that extend the returned base class become both the dependency identifier
-   * and the implementation, providing type safety and clear semantics.
+   * The dependencies array must match the constructor parameters exactly (order and types).
+   * This is validated at compile time.
    *
-   * @template Id - The unique identifier for this service class
-   * @param id - The unique identifier (string or symbol) for this service
-   * @returns A base class that can be extended to create tagged service classes
+   * @param cls - The service class
+   * @param deps - Array of dependencies (tags or raw values) matching constructor params
+   * @param options - Optional cleanup function for the service
    *
-   * @example Basic service class
+   * @example
    * ```typescript
-   * class UserService extends Tag.Service('UserService') {
-   *   getUsers() {
-   *     return ['alice', 'bob'];
-   *   }
+   * class UserService {
+   *   constructor(private db: Database, private apiKey: string) {}
    * }
    *
-   * container.register(UserService, () => new UserService());
+   * const ApiKeyTag = Tag.of('apiKey')<string>();
+   *
+   * // Dependencies must match constructor: (Database, string)
+   * const userLayer = Layer.service(UserService, [Database, ApiKeyTag]);
+   *
+   * // Also works with raw values
+   * const userLayer2 = Layer.service(UserService, [Database, 'my-api-key']);
    * ```
+   */
+  service<TClass extends ServiceTag, const TDeps extends readonly unknown[]>(cls: TClass, deps: TDeps & ValidDepsFor<ConstructorParameters<TClass>>, options?: {
+    cleanup?: Finalizer<InstanceType<TClass>>;
+  }): Layer<ExtractTags<TDeps>, TClass>;
+  /**
+   * Creates a layer that provides a constant value.
    *
-   * @example Service with dependencies
+   * @param tag - The ValueTag to register
+   * @param value - The value to provide
+   *
+   * @example
    * ```typescript
-   * class DatabaseService extends Tag.Service('DatabaseService') {
-   *   query(sql: string) { return []; }
-   * }
+   * const ApiKeyTag = Tag.of('apiKey')<string>();
+   * const ConfigTag = Tag.of('config')<{ port: number }>();
    *
-   * class UserRepository extends Tag.Service('UserRepository') {
-   *   constructor(private db: DatabaseService) {
-   *     super();
-   *   }
+   * const configLayer = Layer.value(ApiKeyTag, 'secret-key')
+   *   .merge(Layer.value(ConfigTag, { port: 3000 }));
+   * ```
+   */
+  value<T extends ValueTag<TagId, unknown>>(tag: T, value: TagType<T>): Layer<never, T>;
+  /**
+   * Creates a custom layer with full control over the factory logic.
    *
-   *   findUser(id: string) {
-   *     return this.db.query(`SELECT * FROM users WHERE id = ${id}`);
-   *   }
-   * }
+   * Use this when you need custom instantiation logic that can't be expressed
+   * with `Layer.service()` or `Layer.value()`.
    *
-   * container
-   *   .register(DatabaseService, () => new DatabaseService())
-   *   .register(UserRepository, async (ctx) =>
-   *     new UserRepository(await ctx.resolve(DatabaseService))
-   *   );
-   * ```
+   * - `TRequires` is inferred from the `requires` array
+   * - `TProvides` is inferred from what `apply` adds to the builder
+   *
+   * @param options.requires - Array of tags this layer requires (use [] for no requirements)
+   * @param options.apply - Function that adds registrations to a builder
    *
-   * @example With symbol identifiers
+   * @example
    * ```typescript
-   * const ServiceId = Symbol('InternalService');
+   * // Layer with dependencies - TProvides inferred from builder.add()
+   * const cacheLayer = Layer.create({
+   *   requires: [Database],
+   *   apply: (builder) => builder
+   *     .add(Cache, async (ctx) => {
+   *       const db = await ctx.resolve(Database);
+   *       return new Cache(db, { ttl: 3600 });
+   *     })
+   * });
+   * // Type: Layer<typeof Database, typeof Cache>
    *
-   * class InternalService extends Tag.Service(ServiceId) {
-   *   doInternalWork() { return 'work'; }
-   * }
+   * // Layer with no dependencies
+   * const dbLayer = Layer.create({
+   *   requires: [],
+   *   apply: (builder) => builder.add(Database, () => new Database())
+   * });
+   * // Type: Layer<never, typeof Database>
    * ```
    */
-  Service: <Id extends TagId>(id: Id) => ServiceTag<Id, {
-    readonly "sandly/ServiceTagIdKey"?: Id;
-  }>;
+  create<const TRequires extends readonly AnyTag[], TAllTags extends AnyTag>(options: {
+    requires: TRequires;
+    apply: (builder: IContainerBuilder<TRequires[number]>) => IContainerBuilder<TAllTags>;
+  }): Layer<TRequires[number], Exclude<TAllTags, TRequires[number]>>;
   /**
-   * Extracts the string representation of a tag's identifier.
+   * Creates an empty layer with no requirements or provisions.
    *
-   * This utility function returns a human-readable string for any tag's identifier,
-   * whether it's a string-based or symbol-based tag. Primarily used internally
-   * for error messages and debugging.
+   * @example
+   * ```typescript
+   * const baseLayer = Layer.empty()
+   *   .merge(configLayer)
+   *   .merge(serviceLayer);
+   * ```
+   */
+  empty(): Layer<never, never>;
+  /**
+   * Merges multiple layers at once.
    *
-   * @param tag - Any valid dependency tag (value tag or service tag)
-   * @returns String representation of the tag's identifier
+   * @param layers - At least 2 layers to merge
+   * @returns A layer combining all requirements and provisions
    *
    * @example
    * ```typescript
-   * const StringTag = Tag.of('myString')<string>();
-   * class ServiceClass extends Tag.Service('MyService') {}
-   *
-   * console.log(Tag.id(StringTag)); // "myString"
-   * console.log(Tag.id(ServiceClass)); // "MyService"
+   * const infraLayer = Layer.mergeAll(
+   *   persistenceLayer,
+   *   messagingLayer,
+   *   observabilityLayer
+   * );
    * ```
-   *
-   * @internal - Primarily for internal use in error messages and debugging
    */
-  id: (tag: AnyTag) => TagId | undefined;
-  isTag: (tag: unknown) => tag is AnyTag;
+  mergeAll<T extends readonly [AnyLayer, AnyLayer, ...AnyLayer[]]>(...layers: T): Layer<UnionOfRequires<T>, UnionOfProvides<T>>;
+  /**
+   * Merges exactly two layers.
+   * Equivalent to `layer1.merge(layer2)`.
+   */
+  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>;
 };
-/**
- * String used to store the original ValueTag in Inject<T> types.
- * This prevents property name collisions while allowing type-level extraction.
- */
-declare const InjectSource = "sandly/InjectSource";
-/**
- * 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.Service('UserService') {
- *   constructor(
- *     private db: DatabaseService,        // ServiceTag - works automatically
- *     private apiKey: Inject<typeof ApiKeyTag>  // ValueTag - type is string, tag preserved
- *   ) {
- *     super();
- *   }
- * }
- * ```
- */
-type Inject<T extends ValueTag<TagId, unknown>> = T extends ValueTag<any, infer V> ? 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; //#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.
+ * Factory function that creates a dependency instance.
  *
- * Factory functions are the core mechanism for dependency creation in the DI system.
- * They receive a dependency container and can use it to resolve other dependencies
- * that the service being created needs.
- *
- * The factory can be either synchronous (returning T directly) or asynchronous
- * (returning Promise<T>). The container handles both cases transparently.
+ * Receives a resolution context for injecting other dependencies.
+ * Can be synchronous or asynchronous.
  *
  * @template T - The type of the service instance being created
- * @template TRequires - Union type of all required dependencies
- *
- * @example Synchronous factory
- * ```typescript
- * 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 (ctx) => {
- *   const [config, db] = await Promise.all([
- *     ctx.resolve(ConfigTag),
- *     ctx.resolve(DatabaseService)
- *   ]);
- *   return new UserService(config, db);
- * };
- * ```
+ * @template TRequires - Union type of required dependencies
  */
 type Factory<T, TRequires extends AnyTag> = (ctx: ResolutionContext<TRequires>) => PromiseOrValue<T>;
 /**
- * Type representing a finalizer function used to clean up dependency instances.
- *
- * Finalizers are optional cleanup functions that are called when the container
- * is destroyed via `container.destroy()`. They receive the created instance
- * and should perform any necessary cleanup (closing connections, releasing resources, etc.).
- *
- * Like factories, finalizers can be either synchronous or asynchronous.
- * All finalizers are called concurrently during container destruction.
- *
- * @template T - The type of the service instance being finalized
- *
- * @example Synchronous finalizer
- * ```typescript
- * const cleanup: Finalizer<FileHandle> = (fileHandle) => {
- *   fileHandle.close();
- * };
- * ```
- *
- * @example Asynchronous finalizer
- * ```typescript
- * const cleanup: Finalizer<DatabaseConnection> = async (connection) => {
- *   await connection.disconnect();
- * };
- * ```
+ * Cleanup function called when the container is destroyed.
  *
- * @example Resilient finalizer
- * ```typescript
- * const cleanup: Finalizer<HttpServer> = async (server) => {
- *   try {
- *     await server.close();
- *   } catch (error) {
- *     if (!error.message.includes('already closed')) {
- *       throw error; // Re-throw unexpected errors
- *     }
- *     // Ignore "already closed" errors
- *   }
- * };
- * ```
+ * @template T - The type of the service instance being cleaned up
  */
 type Finalizer<T> = (instance: T) => PromiseOrValue<void>;
 /**
- * Type representing a complete dependency lifecycle with both factory and finalizer.
- *
- * This interface is used when registering dependencies that need cleanup. Instead of
- * passing separate factory and finalizer parameters, you can pass an object
- * containing both.
+ * Complete dependency lifecycle with factory and optional cleanup.
  *
- * Since this is an interface, you can also implement it as a class for better
- * organization and reuse. This is particularly useful when you have complex
- * lifecycle logic or want to share lifecycle definitions across multiple services.
+ * Can be implemented as a class for complex lifecycle logic.
  *
  * @template T - The instance type
- * @template TRequires - Union type of all required dependencies
- *
- * @example Using DependencyLifecycle as an object
- * ```typescript
- * import { Container, Tag } from 'sandly';
- *
- * class DatabaseConnection extends Tag.Service('DatabaseConnection') {
- *   async connect() { return; }
- *   async disconnect() { return; }
- * }
- *
- * const lifecycle: DependencyLifecycle<DatabaseConnection, never> = {
- *   create: async () => {
- *     const conn = new DatabaseConnection();
- *     await conn.connect();
- *     return conn;
- *   },
- *   cleanup: async (conn) => {
- *     await conn.disconnect();
- *   }
- * };
- *
- * Container.empty().register(DatabaseConnection, lifecycle);
- * ```
- *
- * @example Implementing DependencyLifecycle as a class with dependencies
- * ```typescript
- * import { Container, Tag, type ResolutionContext } from 'sandly';
- *
- * class Logger extends Tag.Service('Logger') {
- *   log(message: string) { console.log(message); }
- * }
- *
- * class DatabaseConnection extends Tag.Service('DatabaseConnection') {
- *   constructor(private logger: Logger, private url: string) { super(); }
- *   async connect() { this.logger.log('Connected'); }
- *   async disconnect() { this.logger.log('Disconnected'); }
- * }
- *
- * class DatabaseLifecycle implements DependencyLifecycle<DatabaseConnection, typeof Logger> {
- *   constructor(private url: string) {}
- *
- *   async create(ctx: ResolutionContext<typeof Logger>): Promise<DatabaseConnection> {
- *     const logger = await ctx.resolve(Logger);
- *     const conn = new DatabaseConnection(logger, this.url);
- *     await conn.connect();
- *     return conn;
- *   }
- *
- *   async cleanup(conn: DatabaseConnection): Promise<void> {
- *     await conn.disconnect();
- *   }
- * }
- *
- * const container = Container.empty()
- *   .register(Logger, () => new Logger())
- *   .register(DatabaseConnection, new DatabaseLifecycle('postgresql://localhost:5432'));
- * ```
- *
- * @example Class with only factory (no cleanup)
- * ```typescript
- * import { Container, Tag } from 'sandly';
- *
- * class SimpleService extends Tag.Service('SimpleService') {}
- *
- * class SimpleServiceLifecycle implements DependencyLifecycle<SimpleService, never> {
- *   create(): SimpleService {
- *     return new SimpleService();
- *   }
- *   // cleanup is optional, so it can be omitted
- * }
- *
- * const container = Container.empty().register(
- *   SimpleService,
- *   new SimpleServiceLifecycle()
- * );
- * ```
+ * @template TRequires - Union type of required dependencies
  */
 interface DependencyLifecycle<T, TRequires extends AnyTag> {
   create: Factory<T, TRequires>;
   cleanup?: Finalizer<T>;
 }
 /**
- * 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 TRequires - Union type of all required dependencies
- *
- * @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> = {
- *   create: () => new DatabaseConnection(),
- *   cleanup: (conn) => conn.close()
- * };
- *
- * Container.empty().register(DatabaseConnection, spec);
- * ```
+ * Valid dependency registration: either a factory function or lifecycle object.
  */
 type DependencySpec<T extends AnyTag, TRequires extends AnyTag> = Factory<TagType<T>, TRequires> | DependencyLifecycle<TagType<T>, TRequires>;
 /**
- * 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.
+ * Context available to factory functions during resolution.
  *
- * @template TTags - Union type of all dependencies available in the container
+ * Provides `resolve` and `resolveAll` for injecting dependencies.
  */
 type ResolutionContext<TTags extends AnyTag> = Pick<IContainer<TTags>, 'resolve' | 'resolveAll'>;
+/**
+ * Unique symbol for container type branding.
+ */
 declare const ContainerTypeId: unique symbol;
 /**
- * Interface representing a container that can register and retrieve dependencies.
+ * Interface for dependency containers.
  *
- * @template TTags - Union type of all dependencies available in the container
+ * @template TTags - Union type of registered dependency tags
  */
 interface IContainer<TTags extends AnyTag = never> {
   readonly [ContainerTypeId]: {
     readonly _TTags: Contravariant<TTags>;
   };
-  register: <T extends AnyTag>(tag: T, spec: DependencySpec<T, TTags>) => IContainer<TTags | T>;
-  has(tag: AnyTag): boolean;
-  exists(tag: AnyTag): boolean;
   resolve: <T extends TTags>(tag: T) => Promise<TagType<T>>;
   resolveAll: <const T extends readonly TTags[]>(...tags: T) => Promise<{ [K in keyof T]: TagType<T[K]> }>;
+  use: <T extends TTags, R>(tag: T, fn: (service: TagType<T>) => PromiseOrValue<R>) => Promise<R>;
   destroy(): Promise<void>;
 }
 /**
- * Extracts the registered tags (TTags) from a container type.
+ * Extracts the registered tags from a container type.
  */
 type ContainerTags<C> = C extends IContainer<infer TTags> ? TTags : never;
 /**
- * A type-safe dependency injection container that manages service instantiation,
- * caching, and lifecycle management with support for async dependencies and
- * circular dependency detection.
+ * Common interface for container builders that support adding dependencies.
+ * Used by Layer to work with both ContainerBuilder and ScopedContainerBuilder.
+ */
+interface IContainerBuilder<TTags extends AnyTag = never> {
+  add<T extends AnyTag>(tag: T, spec: DependencySpec<T, TTags>): IContainerBuilder<TTags | T>;
+}
+/**
+ * Extracts the registered tags from a builder type.
+ */
+type BuilderTags<B> = B extends IContainerBuilder<infer TTags> ? TTags : never;
+/**
+ * Builder for constructing immutable containers.
  *
- * The container maintains complete type safety by tracking registered dependencies
- * at the type level, ensuring that only registered dependencies can be retrieved
- * and preventing runtime errors.
+ * Use `Container.builder()` to create a builder, then chain `.add()` calls
+ * to register dependencies, and finally call `.build()` to create the container.
  *
- * @template TTags - Union type of all registered dependency tags in this container
+ * @template TTags - Union type of registered dependency tags
  *
- * @example Basic usage with service tags
+ * @example
  * ```typescript
- * import { container, Tag } from 'sandly';
- *
- * class DatabaseService extends Tag.Service('DatabaseService') {
- *   query() { return 'data'; }
- * }
- *
- * class UserService extends Tag.Service('UserService') {
- *   constructor(private db: DatabaseService) {}
- *   getUser() { return this.db.query(); }
- * }
- *
- * const container = Container.empty()
- *   .register(DatabaseService, () => new DatabaseService())
- *   .register(UserService, async (ctx) =>
- *     new UserService(await ctx.resolve(DatabaseService))
- *   );
- *
- * const userService = await c.resolve(UserService);
+ * const container = Container.builder()
+ *   .add(Database, () => new Database())
+ *   .add(UserService, async (ctx) =>
+ *     new UserService(await ctx.resolve(Database))
+ *   )
+ *   .build();
  * ```
+ */
+declare class ContainerBuilder<TTags extends AnyTag = never> {
+  private readonly factories;
+  private readonly finalizers;
+  /**
+   * Registers a dependency with a factory function or lifecycle object.
+   *
+   * @param tag - The dependency tag (class or ValueTag)
+   * @param spec - Factory function or lifecycle object
+   * @returns The builder with updated type information
+   */
+  add<T extends AnyTag>(tag: T, spec: DependencySpec<T, TTags>): ContainerBuilder<TTags | T>;
+  /**
+   * Creates an immutable container from the registered dependencies.
+   */
+  build(): Container<TTags>;
+}
+/**
+ * Type-safe dependency injection container.
  *
- * @example Usage with value tags
- * ```typescript
- * const ApiKeyTag = Tag.of('apiKey')<string>();
- * const ConfigTag = Tag.of('config')<{ dbUrl: string }>();
- *
- * const container = Container.empty()
- *   .register(ApiKeyTag, () => process.env.API_KEY!)
- *   .register(ConfigTag, () => ({ dbUrl: 'postgresql://localhost:5432' }));
+ * Containers are immutable - use `Container.builder()` to create one.
+ * Each dependency is created once (singleton) and cached.
  *
- * const apiKey = await c.resolve(ApiKeyTag);
- * const config = await c.resolve(ConfigTag);
- * ```
+ * @template TTags - Union type of registered dependency tags
  *
- * @example With finalizers for cleanup
+ * @example
  * ```typescript
- * class DatabaseConnection extends Tag.Service('DatabaseConnection') {
- *   async connect() { return; }
- *   async disconnect() { return; }
+ * class Database {
+ *   query(sql: string) { return []; }
+ * }
+ *
+ * class UserService {
+ *   constructor(private db: Database) {}
+ *   getUsers() { return this.db.query('SELECT * FROM users'); }
  * }
  *
- * const container = Container.empty().register(
- *   DatabaseConnection,
- *   async () => {
- *     const conn = new DatabaseConnection();
- *     await conn.connect();
- *     return conn;
- *   },
- *   async (conn) => conn.disconnect() // Finalizer for cleanup
- * );
+ * const container = Container.builder()
+ *   .add(Database, () => new Database())
+ *   .add(UserService, async (ctx) =>
+ *     new UserService(await ctx.resolve(Database))
+ *   )
+ *   .build();
  *
- * // Later...
- * await c.destroy(); // Calls all finalizers
+ * const userService = await container.resolve(UserService);
  * ```
  */
-declare class Container<TTags extends AnyTag> implements IContainer<TTags> {
+declare class Container<TTags extends AnyTag = never> implements IContainer<TTags> {
   readonly [ContainerTypeId]: {
     readonly _TTags: Contravariant<TTags>;
   };
-  protected constructor();
   /**
-   * Cache of instantiated dependencies as promises.
-   * Ensures singleton behavior and supports concurrent access.
+   * Cache of instantiated dependencies.
    * @internal
    */
   protected readonly cache: Map<AnyTag, Promise<unknown>>;
   /**
-   * Factory functions for creating dependency instances.
+   * Factory functions for creating dependencies.
    * @internal
    */
   protected readonly factories: Map<AnyTag, Factory<unknown, TTags>>;
   /**
-   * Finalizer functions for cleaning up dependencies when the container is destroyed.
+   * Cleanup functions for dependencies.
    * @internal
    */
   protected readonly finalizers: Map<AnyTag, Finalizer<any>>;
   /**
-   * Flag indicating whether this container has been destroyed.
+   * Whether this container has been destroyed.
    * @internal
    */
   protected isDestroyed: boolean;
   /**
-   * Creates a new empty container instance.
-   * @returns A new empty Container instance with no registered dependencies.
+   * @internal - Use Container.builder() or Container.empty()
    */
-  static empty(): Container<never>;
+  protected constructor(factories: Map<AnyTag, Factory<unknown, TTags>>, finalizers: Map<AnyTag, Finalizer<any>>);
   /**
-   * 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 `.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 {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.Service('LoggerService') {
-   *   log(message: string) { console.log(message); }
-   * }
-   *
-   * const container = Container.empty().register(
-   *   LoggerService,
-   *   () => new LoggerService()
-   * );
-   * ```
+   * @internal - Used by ContainerBuilder
+   */
+  static _createFromBuilder<T extends AnyTag>(factories: Map<AnyTag, Factory<unknown, T>>, finalizers: Map<AnyTag, Finalizer<any>>): Container<T>;
+  /**
+   * Creates a new container builder.
    *
-   * @example Registering with dependencies
+   * @example
    * ```typescript
-   * class UserService extends Tag.Service('UserService') {
-   *   constructor(private db: DatabaseService, private logger: LoggerService) {}
-   * }
-   *
-   * const container = Container.empty()
-   *   .register(DatabaseService, () => new DatabaseService())
-   *   .register(LoggerService, () => new LoggerService())
-   *   .register(UserService, async (ctx) =>
-   *     new UserService(
-   *       await ctx.resolve(DatabaseService),
-   *       await ctx.resolve(LoggerService)
-   *     )
-   *   );
+   * const container = Container.builder()
+   *   .add(Database, () => new Database())
+   *   .build();
    * ```
+   */
+  static builder(): ContainerBuilder;
+  /**
+   * Creates an empty container with no dependencies.
    *
-   * @example Overriding a dependency
-   * ```typescript
-   * const container = Container.empty()
-   *   .register(DatabaseService, () => new DatabaseService())
-   *   .register(DatabaseService, () => new MockDatabaseService()); // Overrides the previous registration
-   * ```
+   * Shorthand for `Container.builder().build()`.
+   */
+  static empty(): Container;
+  /**
+   * Creates a scoped container for hierarchical dependency management.
    *
-   * @example Using value tags
-   * ```typescript
-   * const ConfigTag = Tag.of('config')<{ apiUrl: string }>();
+   * Scoped containers support parent/child relationships where children
+   * can access parent dependencies but maintain their own cache.
    *
-   * const container = Container.empty().register(
-   *   ConfigTag,
-   *   () => ({ apiUrl: 'https://api.example.com' })
-   * );
-   * ```
+   * @param scope - Identifier for the scope (for debugging)
    *
-   * @example With finalizer for cleanup
+   * @example
    * ```typescript
-   * class DatabaseConnection extends Tag.Service('DatabaseConnection') {
-   *   async connect() { return; }
-   *   async close() { return; }
-   * }
+   * const appContainer = Container.scoped('app');
+   * // ... add app-level dependencies
    *
-   * const container = Container.empty().register(
-   *   DatabaseConnection,
-   *   async () => {
-   *     const conn = new DatabaseConnection();
-   *     await conn.connect();
-   *     return conn;
-   *   },
-   *   (conn) => conn.close() // Called during container.destroy()
-   * );
+   * const requestContainer = appContainer.child('request');
+   * // ... add request-specific dependencies
    * ```
    */
-  register<T extends AnyTag>(tag: T, spec: DependencySpec<T, TTags>): Container<TTags | T>;
+  static scoped(scope: string | symbol): ScopedContainer;
   /**
-   * Checks if a dependency has been registered in the container.
+   * Creates a container from a layer.
    *
-   * This returns `true` if the dependency has been registered via `.register()`,
-   * regardless of whether it has been instantiated yet.
+   * This is a convenience method equivalent to applying a layer to
+   * `Container.builder()` and building the result.
    *
-   * @param tag - The dependency tag to check
-   * @returns `true` if the dependency has been registered, `false` otherwise
+   * @param layer - A layer with no requirements (all dependencies satisfied)
    *
    * @example
    * ```typescript
-   * const container = 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.
+   * const dbLayer = Layer.service(Database, []);
+   * const container = Container.from(dbLayer);
    *
-   * @param tag - The dependency tag to check
-   * @returns true if the dependency has been instantiated, false otherwise
+   * const db = await container.resolve(Database);
+   * ```
    */
-  exists(tag: AnyTag): boolean;
+  static from<TProvides extends AnyTag>(layer: Layer<never, TProvides>): Container<TProvides>;
   /**
-   * Retrieves a dependency instance from the container, creating it if necessary.
+   * Resolves a dependency, creating it if necessary.
    *
-   * This method ensures singleton behavior - each dependency is created only once
-   * and cached for subsequent calls. The method is async-safe and handles concurrent
-   * requests for the same dependency correctly.
+   * Dependencies are singletons - the same instance is returned on subsequent calls.
    *
-   * The method performs circular dependency detection by tracking the resolution chain
-   * through the resolution context.
-   *
-   * @template T - The dependency tag type (must be registered in this container)
-   * @param tag - The dependency tag to retrieve
-   * @returns Promise resolving to the service instance
-   * @throws {UnknownDependencyError} If the dependency is not registered
+   * @param tag - The dependency tag to resolve
+   * @returns Promise resolving to the dependency instance
+   * @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 the factory function throws an error
-   *
-   * @example Basic usage
-   * ```typescript
-   * const container = Container.empty()
-   *   .register(DatabaseService, () => new DatabaseService());
-   *
-   * const db = await c.resolve(DatabaseService);
-   * db.query('SELECT * FROM users');
-   * ```
-   *
-   * @example Concurrent access (singleton behavior)
-   * ```typescript
-   * // All three calls will receive the same instance
-   * const [db1, db2, db3] = await Promise.all([
-   *   c.resolve(DatabaseService),
-   *   c.resolve(DatabaseService),
-   *   c.resolve(DatabaseService)
-   * ]);
-   *
-   * console.log(db1 === db2 === db3); // true
-   * ```
-   *
-   * @example Dependency injection in factories
-   * ```typescript
-   * const container = Container.empty()
-   *   .register(DatabaseService, () => new DatabaseService())
-   *   .register(UserService, async (ctx) => {
-   *     const db = await ctx.resolve(DatabaseService);
-   *     return new UserService(db);
-   *   });
-   *
-   * const userService = await c.resolve(UserService);
-   * ```
+   * @throws {DependencyCreationError} If any factory function throws an error
    */
   resolve<T extends TTags>(tag: T): Promise<TagType<T>>;
   /**
-   * Internal resolution method that tracks the dependency chain for circular dependency detection.
-   * Can be overridden by subclasses (e.g., ScopedContainer) to implement custom resolution logic.
+   * Internal resolution with dependency chain tracking.
    * @internal
    */
   protected resolveInternal<T extends TTags>(tag: T, chain: AnyTag[]): 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.
+   * Resolves multiple dependencies concurrently.
    *
-   * @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
+   * @param tags - The dependency tags to resolve
+   * @returns Promise resolving to a tuple of instances
    * @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 container = 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 container = 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 TTags[]>(...tags: T): Promise<{ [K in keyof T]: TagType<T[K]> }>;
   /**
-   * Destroys all instantiated dependencies by calling their finalizers and makes the container unusable.
-   *
-   * **Important: After calling destroy(), the container becomes permanently unusable.**
-   * Any subsequent calls to register(), get(), or destroy() will throw a DependencyFinalizationError.
-   * 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.
-   * If any finalizers fail, all errors are collected and a DependencyFinalizationError
-   * is thrown containing details of all failures.
+   * Resolves a service, runs the callback with it, then destroys the container.
    *
-   * **Finalizer Concurrency:** Finalizers run concurrently, so there are no ordering guarantees.
-   * Services should be designed to handle cleanup gracefully regardless of the order in which their
-   * dependencies are cleaned up.
+   * This is a convenience method for the common "create, use, destroy" pattern.
+   * The container is always destroyed after the callback completes, even if it throws.
    *
-   * @returns Promise that resolves when all cleanup is complete
-   * @throws {DependencyFinalizationError} If any finalizers fail during cleanup
-   *
-   * @example Basic cleanup
-   * ```typescript
-   * const container = Container.empty()
-   *   .register(DatabaseConnection,
-   *     async () => {
-   *       const conn = new DatabaseConnection();
-   *       await conn.connect();
-   *       return conn;
-   *     },
-   *     (conn) => conn.disconnect() // Finalizer
-   *   );
-   *
-   * const db = await c.resolve(DatabaseConnection);
-   * await c.destroy(); // Calls conn.disconnect(), container becomes unusable
-   *
-   * // This will throw an error
-   * try {
-   *   await c.resolve(DatabaseConnection);
-   * } catch (error) {
-   *   console.log(error.message); // "Cannot resolve dependencies from a destroyed container"
-   * }
-   * ```
-   *
-   * @example Application shutdown
-   * ```typescript
-   * 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);
-   * });
-   * ```
+   * @param tag - The dependency tag to resolve
+   * @param fn - Callback that receives the resolved service
+   * @returns Promise resolving to the callback's return value
+   * @throws {ContainerDestroyedError} If the container has been destroyed
+   * @throws {UnknownDependencyError} If the dependency is not registered
+   * @throws {CircularDependencyError} If a circular dependency is detected
+   * @throws {DependencyCreationError} If the factory function throws
+   * @throws {DependencyFinalizationError} If the finalizer function throws
    *
-   * @example Handling cleanup errors
+   * @example
    * ```typescript
-   * try {
-   *   await container.destroy();
-   * } catch (error) {
-   *   if (error instanceof DependencyContainerFinalizationError) {
-   *     console.error('Some dependencies failed to clean up:', error.detail.errors);
-   *   }
-   * }
-   * // Container is destroyed regardless of finalizer errors
+   * const result = await container.use(UserService, (service) =>
+   *   service.getUsers()
+   * );
+   * // Container is automatically destroyed after callback completes
    * ```
    */
-  destroy(): Promise<void>;
-}
-
-//#endregion
-//#region src/scoped-container.d.ts
-type Scope = string | symbol;
-declare class ScopedContainer<TTags extends AnyTag> extends Container<TTags> {
-  readonly scope: Scope;
-  private parent;
-  private readonly children;
-  protected constructor(parent: IContainer<TTags> | null, scope: Scope);
-  /**
-   * Creates a new empty scoped container instance.
-   * @param scope - The scope identifier for this container
-   * @returns A new empty ScopedContainer instance with no registered dependencies
-   */
-  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, TTags>): ScopedContainer<TTags | 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 TTags>(tag: T): Promise<TagType<T>>;
-  /**
-   * Internal resolution with delegation logic for scoped containers.
-   * @internal
-   */
-  protected resolveInternal<T extends TTags>(tag: T, chain: AnyTag[]): Promise<TagType<T>>;
+  use<T extends TTags, R>(tag: T, fn: (service: TagType<T>) => PromiseOrValue<R>): Promise<R>;
   /**
-   * Destroys this scoped container and its children, preserving the container structure for reuse.
+   * Destroys the container, calling all finalizers.
    *
-   * 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
+   * After destruction, the container cannot be used.
+   * Finalizers run concurrently, so there are no ordering guarantees.
+   * Services should be designed to handle cleanup gracefully regardless of the order in which their
+   * dependencies are cleaned up.
    *
-   * Child destruction happens first to ensure dependencies don't get cleaned up
-   * before their dependents.
+   * @throws {DependencyFinalizationError} If any finalizers fail
    */
   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(scope: Scope): ScopedContainer<TTags>;
 }
-
-//#endregion
-//#region src/layer.d.ts
 /**
- * Replaces the TTags type parameter in a container type with a new type.
- * Preserves the concrete container type (Container, ScopedContainer, or IContainer).
- *
- * Uses contravariance to detect container types:
- * - Any ScopedContainer<X> extends ScopedContainer<never>
- * - Any Container<X> extends Container<never> (but not ScopedContainer<never>)
- * - Falls back to IContainer for anything else
- * @internal
- */
-type WithContainerTags<TContainer, TNewTags extends AnyTag> = TContainer extends ScopedContainer<never> ? ScopedContainer<TNewTags> : TContainer extends Container<never> ? Container<TNewTags> : IContainer<TNewTags>;
-/**
- * The most generic layer type that accepts any concrete layer.
+ * Scope identifier type.
  */
-type AnyLayer = Layer<any, any>;
-/**
- * The type ID for the Layer interface.
- */
-declare const LayerTypeId: unique symbol;
+type Scope = string | 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 'sandly';
- *
- * class DatabaseService extends Tag.Service('DatabaseService') {
- *   query() { return 'data'; }
- * }
- *
- * // Create a layer that provides DatabaseService
- * const databaseLayer = layer<never, typeof DatabaseService>((container) =>
- *   container.register(DatabaseService, () => new DatabaseService())
- * );
- *
- * // Apply the layer to a container
- * const container = Container.empty();
- * const finalContainer = databaseLayer.register(c);
- *
- * const db = await finalContainer.resolve(DatabaseService);
- * ```
- *
- * @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 (ctx) =>
- *     new UserService(await ctx.resolve(DatabaseService))
- *   )
- * );
+ * Builder for constructing scoped containers.
  *
- * // Compose layers: provide database layer to user layer
- * const appLayer = userLayer.provide(databaseLayer);
- * ```
+ * @template TTags - Union type of registered dependency tags
  */
-interface Layer<TRequires extends AnyTag, TProvides extends AnyTag> {
-  readonly [LayerTypeId]?: {
-    readonly _TRequires: Covariant<TRequires>;
-    readonly _TProvides: Contravariant<TProvides>;
-  };
+declare class ScopedContainerBuilder<TTags extends AnyTag = never> {
+  private readonly scope;
+  private readonly parent;
+  private readonly factories;
+  private readonly finalizers;
+  constructor(scope: Scope, parent: IContainer<TTags> | null);
   /**
-   * Applies this layer's registrations to the given container.
-   *
-   * ## Generic Container Support
-   *
-   * 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.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
-   * ```
+   * Registers a dependency with a factory function or lifecycle object.
    */
-  register: <TContainer extends IContainer<TRequires>>(container: TContainer) => WithContainerTags<TContainer, ContainerTags<TContainer> | TProvides>;
-  /**
-   * 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: 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 only exposes this layer's provisions
-   *
-   * @example Simple composition
-   * ```typescript
-   * const configLayer = layer<never, typeof ConfigTag>(...);
-   * const dbLayer = layer<typeof ConfigTag, typeof DatabaseService>(...);
-   *
-   * // 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 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>
-   * ```
-   */
-  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
-   * relationship.
-   *
-   * @template TOtherRequires - What the other layer requires
-   * @template TOtherProvides - What the other layer provides
-   * @param other - The layer to merge with
-   * @returns A new merged layer requiring both layers' requirements and providing both layers' provisions
-   *
-   * @example Merging independent layers
-   * ```typescript
-   * const persistenceLayer = layer<never, typeof DatabaseService | typeof CacheService>(...);
-   * const loggingLayer = layer<never, typeof LoggerService>(...);
-   *
-   * // Combine infrastructure layers
-   * const infraLayer = persistenceLayer.merge(loggingLayer);
-   * ```
-   *
-   * @example Building complex layer combinations
-   * ```typescript
-   * const appInfraLayer = persistenceLayer
-   *   .merge(messagingLayer)
-   *   .merge(observabilityLayer);
-   * ```
+  add<T extends AnyTag>(tag: T, spec: DependencySpec<T, TTags>): ScopedContainerBuilder<TTags | T>;
+  /**
+   * Creates an immutable scoped container from the registered dependencies.
    */
-  merge: <TOtherRequires extends AnyTag, TOtherProvides extends AnyTag>(other: Layer<TOtherRequires, TOtherProvides>) => Layer<TRequires | TOtherRequires, TProvides | TOtherProvides>;
+  build(): ScopedContainer<TTags>;
 }
 /**
- * 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
- *
- * @param register - Function that performs the dependency registrations. Receives a container.
- * @returns The layer instance.
- *
- * @example Simple layer
- * ```typescript
- * import { layer, Tag } from 'sandly';
- *
- * class DatabaseService extends Tag.Service('DatabaseService') {
- *   constructor(private url: string = 'sqlite://memory') {}
- *   query() { return 'data'; }
- * }
+ * Scoped container for hierarchical dependency management.
  *
- * // Layer that provides DatabaseService, requires nothing
- * const databaseLayer = layer<never, typeof DatabaseService>((container) =>
- *   container.register(DatabaseService, () => new DatabaseService())
- * );
+ * Supports parent/child relationships where children can access parent
+ * dependencies but maintain their own cache. Useful for request-scoped
+ * dependencies in web applications.
  *
- * // Usage
- * const dbLayerInstance = databaseLayer;
- * ```
+ * @template TTags - Union type of registered dependency tags
  *
- * @example Complex application layer structure
+ * @example
  * ```typescript
- * // Configuration layer
- * const configLayer = layer<never, typeof ConfigTag>((container) =>
- *   container.register(ConfigTag, () => loadConfig())
- * );
- *
- * // Infrastructure layer (requires config)
- * const infraLayer = layer<typeof ConfigTag, typeof DatabaseService | typeof CacheService>(
- *   (container) =>
- *     container
- *       .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 (ctx) =>
- *       new UserService(await ctx.resolve(DatabaseService), await ctx.resolve(CacheService))
- *     )
- * );
- *
- * // Compose the complete application
- * const appLayer = serviceLayer.provide(infraLayer).provide(configLayer);
+ * // Application-level container
+ * const appContainer = ScopedContainer.builder('app')
+ *   .add(Database, () => new Database())
+ *   .build();
+ *
+ * // Request-level container (inherits from app)
+ * const requestContainer = appContainer.child('request')
+ *   .add(RequestContext, () => new RequestContext())
+ *   .build();
+ *
+ * // Can resolve both app and request dependencies
+ * const db = await requestContainer.resolve(Database);
+ * const ctx = await requestContainer.resolve(RequestContext);
  * ```
  */
-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.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 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.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 AnyLayer[]> = { [K in keyof T]: T[K] extends Layer<any, infer P> ? P : never }[number];
-/**
- * Utility object containing helper functions for working with layers.
- */
-declare const Layer: {
+declare class ScopedContainer<TTags extends AnyTag = never> extends Container<TTags> {
+  readonly scope: Scope;
+  private parent;
+  private readonly children;
+  /**
+   * @internal
+   */
+  protected constructor(scope: Scope, parent: IContainer<TTags> | null, factories: Map<AnyTag, Factory<unknown, TTags>>, finalizers: Map<AnyTag, Finalizer<any>>);
   /**
-   * Creates an empty layer that provides no dependencies and requires no dependencies.
-   * This is useful as a base layer or for testing.
+   * @internal - Used by ScopedContainerBuilder
+   */
+  static _createScopedFromBuilder<T extends AnyTag>(scope: Scope, parent: IContainer<T> | null, factories: Map<AnyTag, Factory<unknown, T>>, finalizers: Map<AnyTag, Finalizer<any>>): ScopedContainer<T>;
+  /**
+   * Creates a new scoped container builder.
    *
-   * @returns An empty layer that can be used as a starting point for layer composition
+   * @param scope - Identifier for the scope (for debugging)
    *
    * @example
    * ```typescript
-   * import { Layer } from 'sandly';
-   *
-   * const baseLayer = Layer.empty();
-   * const appLayer = baseLayer
-   *   .merge(configLayer)
-   *   .merge(serviceLayer);
+   * const container = ScopedContainer.builder('app')
+   *   .add(Database, () => new Database())
+   *   .build();
    * ```
    */
-  empty(): Layer<never, never>;
+  static builder(scope: Scope): ScopedContainerBuilder;
   /**
-   * Merges multiple layers at once in a type-safe way.
-   * This is equivalent to chaining `.merge()` calls but more convenient for multiple layers.
-   *
-   * ## Type Safety with Variance
+   * Creates an empty scoped container with no dependencies.
+   */
+  static empty(scope: Scope): ScopedContainer;
+  /**
+   * Creates a scoped container from a layer.
    *
-   * Uses the AnyLayer constraint (Layer<never, AnyTag>) which accepts any concrete layer
-   * through the Layer interface's variance annotations:
+   * This is a convenience method equivalent to applying a layer to
+   * `ScopedContainer.builder()` and building the result.
    *
-   * - **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
+   * @param scope - Identifier for the scope (for debugging)
+   * @param layer - A layer with no requirements (all dependencies satisfied)
    *
-   * The return type correctly extracts and unions the actual requirement/provision types
-   * from all input layers, preserving full type safety.
+   * @example
+   * ```typescript
+   * const dbLayer = Layer.service(Database, []);
+   * const container = ScopedContainer.from('app', dbLayer);
    *
-   * 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.
+   * const db = await container.resolve(Database);
+   * ```
+   */
+  static from<TProvides extends AnyTag>(scope: Scope, layer: Layer<never, TProvides>): ScopedContainer<TProvides>;
+  /**
+   * Resolves a dependency from this scope or parent scopes, creating it if necessary.
    *
-   * @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 with correct union types
+   * Dependencies are singletons - the same instance is returned on subsequent calls.
    *
-   * @example Basic usage with different layer types
-   * ```typescript
-   * import { Layer } from 'sandly';
+   * @param tag - The dependency tag to resolve
+   * @returns Promise resolving to the dependency instance
+   * @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
+   */
+  resolve<T extends TTags>(tag: T): Promise<TagType<T>>;
+  /**
+   * Internal resolution with parent delegation.
+   * @internal
+   */
+  protected resolveInternal<T extends TTags>(tag: T, chain: AnyTag[]): Promise<TagType<T>>;
+  /**
+   * @internal - Used by ScopedContainerBuilder to register children
+   */
+  _registerChild(child: ScopedContainer<TTags>): void;
+  /**
+   * Creates a child container builder that inherits from this container.
    *
-   * // 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
+   * Use this to create a child scope and add dependencies to it.
+   * The child can resolve dependencies from this container.
    *
-   * const infraLayer = Layer.mergeAll(dbLayer, userLayer, configLayer);
-   * // Type: Layer<typeof DatabaseService, typeof DatabaseService | typeof UserService | typeof ConfigService>
-   * ```
+   * @param scope - Identifier for the child scope
+   * @returns A new ScopedContainerBuilder for the child scope
+   * @throws {ContainerDestroyedError} If the container has been destroyed
    *
-   * @example Equivalent to chaining .merge()
+   * @example
    * ```typescript
-   * // These are equivalent:
-   * const layer1 = Layer.mergeAll(layerA, layerB, layerC);
-   * const layer2 = layerA.merge(layerB).merge(layerC);
+   * const requestContainer = appContainer.child('request')
+   *   .add(RequestContext, () => new RequestContext())
+   *   .build();
+   *
+   * await requestContainer.resolve(Database); // From parent
+   * await requestContainer.resolve(RequestContext); // From this scope
    * ```
+   */
+  child(scope: Scope): ScopedContainerBuilder<TTags>;
+  /**
+   * Creates a child container with a layer applied.
    *
-   * @example Building infrastructure layers
-   * ```typescript
-   * const persistenceLayer = layer<never, typeof DatabaseService | typeof CacheService>(...);
-   * const messagingLayer = layer<never, typeof MessageQueue>(...);
-   * const observabilityLayer = layer<never, typeof Logger | typeof Metrics>(...);
+   * This is a convenience method combining child() + layer.apply() + build().
+   * Use this when you have a layer ready to apply.
    *
-   * // Merge all infrastructure concerns into one layer
-   * const infraLayer = Layer.mergeAll(
-   *   persistenceLayer,
-   *   messagingLayer,
-   *   observabilityLayer
+   * @param scope - Identifier for the child scope
+   * @param layer - Layer to apply to the child (can require parent's tags)
+   *
+   * @example
+   * ```typescript
+   * const requestContainer = appContainer.childFrom('request',
+   *   userService
+   *     .provide(Layer.value(TenantContext, tenantCtx))
+   *     .provide(Layer.value(RequestId, requestId))
    * );
    *
-   * // Result type: Layer<never, DatabaseService | CacheService | MessageQueue | Logger | Metrics>
+   * const users = await requestContainer.resolve(UserService);
    * ```
    */
-  mergeAll<T extends readonly [AnyLayer, AnyLayer, ...AnyLayer[]]>(...layers: T): Layer<UnionOfRequires<T>, UnionOfProvides<T>>;
+  childFrom<TProvides extends AnyTag>(scope: Scope, layer: Layer<TTags, TProvides>): ScopedContainer<TTags | TProvides>;
   /**
-   * 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';
+   * Destroys this container and all child containers.
    *
-   * const dbLayer = layer<never, typeof DatabaseService>(...);
-   * const cacheLayer = layer<never, typeof CacheService>(...);
+   * Children are destroyed first to ensure proper cleanup order.
    *
-   * const persistenceLayer = Layer.merge(dbLayer, cacheLayer);
-   * // Type: Layer<never, typeof DatabaseService | typeof CacheService>
-   * ```
+   * After destruction, the container cannot be used.
+   * Finalizers run concurrently, so there are no ordering guarantees.
+   * Services should be designed to handle cleanup gracefully regardless of the order in which their
+   * dependencies are cleaned up.
+   *
+   * @throws {DependencyFinalizationError} If any finalizers fail
    */
-  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/constant.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 = constant(ApiKey, 'my-secret-key');
- * const dbUrl = constant(DatabaseUrl, 'postgresql://localhost:5432/myapp');
- *
- * const config = Layer.merge(apiKey, dbUrl);
- * ```
- */
-declare function constant<T extends ValueTag<TagId, unknown>>(tag: T, constantValue: TagType<T>): Layer<never, T>;
+  destroy(): Promise<void>;
+}
 
 //#endregion
-//#region src/dependency.d.ts
-/**
- * Extracts a union type from a tuple of tags.
- * Returns `never` for empty arrays.
- * @internal
- */
-type TagsToUnion<T extends readonly AnyTag[]> = T[number];
+//#region src/errors.d.ts
 /**
- * Creates a layer that provides a single dependency with inferred requirements.
- *
- * This is a simplified alternative to `layer()` for the common case of defining
- * a single dependency. Unlike `service()` and `autoService()`, this works with
- * any tag type (ServiceTag or ValueTag) and doesn't require extending `Tag.Service()`.
- *
- * Requirements are passed as an optional array of tags, allowing TypeScript to infer
- * both the tag type and the requirements automatically - no explicit type
- * parameters needed.
- *
- * @param tag - The tag (ServiceTag or ValueTag) that identifies this dependency
- * @param spec - Factory function or lifecycle object for creating the dependency
- * @param requirements - Optional array of dependency tags this dependency requires (defaults to [])
- * @returns A layer that requires the specified dependencies and provides the tag
- *
- * @example Simple dependency without requirements
- * ```typescript
- * const Config = Tag.of('Config')<{ apiUrl: string }>();
- *
- * // No requirements - can omit the array
- * const configDep = dependency(Config, () => ({
- *   apiUrl: process.env.API_URL!
- * }));
- * ```
- *
- * @example Dependency with requirements
- * ```typescript
- * const database = dependency(
- *   Database,
- *   async (ctx) => {
- *     const config = await ctx.resolve(Config);
- *     const logger = await ctx.resolve(Logger);
- *     logger.info('Creating database connection');
- *     return createDb(config.DATABASE);
- *   },
- *   [Config, Logger]
- * );
- * ```
- *
- * @example Dependency with lifecycle (create + cleanup)
- * ```typescript
- * const database = dependency(
- *   Database,
- *   {
- *     create: async (ctx) => {
- *       const config = await ctx.resolve(Config);
- *       const logger = await ctx.resolve(Logger);
- *       logger.info('Creating database connection');
- *       return await createDb(config.DATABASE);
- *     },
- *     cleanup: async (db) => {
- *       await disconnectDb(db);
- *     },
- *   },
- *   [Config, Logger]
- * );
- * ```
- *
- * @example Comparison with layer()
- * ```typescript
- * // Using layer() - verbose, requires explicit type parameters
- * const database = layer<typeof Config | typeof Logger, typeof Database>(
- *   (container) =>
- *     container.register(Database, async (ctx) => {
- *       const config = await ctx.resolve(Config);
- *       return createDb(config.DATABASE);
- *     })
- * );
- *
- * // Using dependency() - cleaner, fully inferred types
- * const database = dependency(
- *   Database,
- *   async (ctx) => {
- *     const config = await ctx.resolve(Config);
- *     return createDb(config.DATABASE);
- *   },
- *   [Config, Logger]
- * );
- * ```
+ * Structured error information for debugging and logging.
  */
-declare function dependency<TTag extends AnyTag, TRequirements extends readonly AnyTag[] = []>(tag: TTag, spec: DependencySpec<TTag, TagsToUnion<TRequirements>>, requirements?: TRequirements): Layer<TagsToUnion<TRequirements>, TTag>;
-
-//#endregion
-//#region src/errors.d.ts
 type ErrorDump = {
   name: string;
   message: string;
@@ -1512,17 +884,20 @@ type ErrorDump = {
   detail: Record<string, unknown>;
   cause?: unknown;
 };
+/**
+ * Options for creating Sandly errors.
+ */
 type SandlyErrorOptions = {
   cause?: unknown;
   detail?: Record<string, unknown>;
 };
 /**
- * Base error class for all library errors.
+ * Base error class for all Sandly library errors.
  *
- * This extends the native Error class to provide consistent error handling
+ * Extends the native Error class to provide consistent error handling
  * and structured error information across the library.
  *
- * @example Catching library errors
+ * @example
  * ```typescript
  * try {
  *   await container.resolve(SomeService);
@@ -1540,44 +915,36 @@ declare class SandlyError extends Error {
     cause,
     detail
   }?: SandlyErrorOptions);
+  /**
+   * Wraps any error as a SandlyError.
+   */
   static ensure(error: unknown): SandlyError;
+  /**
+   * Returns a structured representation of the error for logging.
+   */
   dump(): ErrorDump;
+  /**
+   * Returns a JSON string representation of the error.
+   */
   dumps(): string;
   /**
    * Recursively extract cause chain from any Error.
-   * Handles both AppError (with dump()) and plain Errors (with cause property).
    */
   private dumpCause;
 }
-/**
- * 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 SandlyError {}
 /**
  * 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 SandlyError {}
 /**
  * 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 container = Container.empty(); // Empty container
+ * const container = Container.builder().build(); // Empty container
  *
  * try {
- *   await c.resolve(UnregisteredService); // This will throw
+ *   await container.resolve(UnregisteredService);
  * } catch (error) {
  *   if (error instanceof UnknownDependencyError) {
  *     console.error('Missing dependency:', error.message);
@@ -1586,360 +953,81 @@ declare class ContainerDestroyedError extends SandlyError {}
  * ```
  */
 declare class UnknownDependencyError extends SandlyError {
-  /**
-   * @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.
+ * Error thrown when a circular dependency is detected during resolution.
  *
- * @example Circular dependency scenario
+ * @example
  * ```typescript
- * class ServiceA extends Tag.Service('ServiceA') {}
- * class ServiceB extends Tag.Service('ServiceB') {}
- *
- * const container = 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!
- *   );
- *
+ * // ServiceA depends on ServiceB, ServiceB depends on ServiceA
  * try {
- *   await c.resolve(ServiceA);
+ *   await container.resolve(ServiceA);
  * } catch (error) {
  *   if (error instanceof CircularDependencyError) {
  *     console.error('Circular dependency:', error.message);
- *     // Output: "Circular dependency detected for ServiceA: ServiceA -> ServiceB -> ServiceA"
+ *     // "Circular dependency detected for ServiceA: ServiceA -> ServiceB -> ServiceA"
  *   }
  * }
  * ```
  */
 declare class CircularDependencyError extends SandlyError {
-  /**
-   * @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.
+ * Error thrown when a dependency factory throws during instantiation.
  *
- * When dependencies are nested (A depends on B depends on C), and C's factory throws,
- * you get nested DependencyCreationErrors. Use `getRootCause()` to get the original error.
+ * For nested dependencies (A depends on B depends on C), use `getRootCause()`
+ * to unwrap all layers and get the original error.
  *
- * @example Factory throwing error
+ * @example
  * ```typescript
- * class DatabaseService extends Tag.Service('DatabaseService') {}
- *
- * const container = Container.empty().register(DatabaseService, () => {
- *   throw new Error('Database connection failed');
- * });
- *
  * try {
- *   await c.resolve(DatabaseService);
+ *   await container.resolve(UserService);
  * } catch (error) {
  *   if (error instanceof DependencyCreationError) {
  *     console.error('Failed to create:', error.message);
- *     console.error('Original error:', error.cause);
- *   }
- * }
- * ```
- *
- * @example Getting root cause from nested errors
- * ```typescript
- * // ServiceA -> ServiceB -> ServiceC (ServiceC throws)
- * try {
- *   await container.resolve(ServiceA);
- * } catch (error) {
- *   if (error instanceof DependencyCreationError) {
- *     console.error('Top-level error:', error.message); // "Error creating instance of ServiceA"
  *     const rootCause = error.getRootCause();
- *     console.error('Root cause:', rootCause); // Original error from ServiceC
+ *     console.error('Root cause:', rootCause);
  *   }
  * }
  * ```
  */
 declare class DependencyCreationError extends SandlyError {
-  /**
-   * @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);
   /**
    * Traverses the error chain to find the root cause error.
    *
-   * When dependencies are nested, each level wraps the error in a DependencyCreationError.
-   * This method unwraps all the layers to get to the original error that started the failure.
-   *
-   * @returns The root cause error (not a DependencyCreationError unless that's the only error)
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   await container.resolve(UserService);
-   * } catch (error) {
-   *   if (error instanceof DependencyCreationError) {
-   *     const rootCause = error.getRootCause();
-   *     console.error('Root cause:', rootCause);
-   *   }
-   * }
-   * ```
+   * When dependencies are nested, each level wraps the error.
+   * This method unwraps all layers to get the original error.
    */
   getRootCause(): 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.
+ * Even if some finalizers fail, cleanup continues for all others.
+ * This error aggregates all failures.
  *
- * @example Handling finalization errors
+ * @example
  * ```typescript
  * try {
  *   await container.destroy();
  * } catch (error) {
  *   if (error instanceof DependencyFinalizationError) {
- *     console.error('Some finalizers failed');
- *     console.error('Error details:', error.detail.errors);
+ *     console.error('Cleanup failures:', error.getRootCauses());
  *   }
  * }
  * ```
  */
 declare class DependencyFinalizationError extends SandlyError {
   private readonly errors;
-  /**
-   * @internal
-   * Creates a DependencyFinalizationError aggregating multiple finalizer failures.
-   *
-   * @param errors - Array of errors thrown by individual finalizers
-   */
   constructor(errors: unknown[]);
   /**
-   * Returns the root causes of the errors that occurred during finalization.
-   *
-   * @returns An array of the errors that occurred during finalization.
-   * You can expect at least one error in the array.
+   * Returns all root cause errors from the finalization failures.
    */
   getRootCauses(): unknown[];
 }
 
 //#endregion
-//#region src/service.d.ts
-/**
- * Extracts constructor parameter types from a ServiceTag.
- * Only parameters that extend AnyTag are considered as dependencies.
- * @internal
- */
-type ConstructorParams<T extends ServiceTag<TagId, unknown>> = T extends (new (...args: infer A) => unknown) ? A : never;
-/**
- * Helper to normalize a tag type.
- * For ServiceTags, this strips away extra static properties of the class constructor,
- * reducing it to the canonical ServiceTag<Id, Instance> form.
- * @internal
- */
-type CanonicalTag<T extends AnyTag> = T extends ServiceTag<infer Id, infer Instance> ? ServiceTag<Id, Instance> : T;
-/**
- * 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 ExtractConstructorDeps<T extends readonly unknown[]> = T extends readonly [] ? never : { [K in keyof T]: T[K] extends {
-  readonly [ServiceTagIdKey]?: infer Id;
-} ? Id extends TagId ? T[K] extends (new (...args: unknown[]) => infer Instance) ? ServiceTag<Id, Instance> : ServiceTag<Id, T[K]> : never : ExtractInjectTag<T[K]> extends never ? never : ExtractInjectTag<T[K]> }[number];
-/**
- * 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
- */
-type InferConstructorDepsTuple<T extends readonly unknown[]> = T extends readonly [] ? never : { [K in keyof T]: T[K] extends {
-  readonly [ServiceTagIdKey]?: infer Id;
-} ? Id extends TagId ? T[K] extends (new (...args: unknown[]) => infer Instance) ? ServiceTag<Id, Instance> : ServiceTag<Id, T[K]> : never : ExtractInjectTag<T[K]> extends never ? T[K] : ExtractInjectTag<T[K]> };
-/**
- * Union of all dependency tags a ServiceTag constructor requires.
- * Filters out non‑DI parameters.
- */
-type ServiceDependencies<T extends ServiceTag<TagId, unknown>> = ExtractConstructorDeps<ConstructorParams<T>> extends AnyTag ? ExtractConstructorDeps<ConstructorParams<T>> : never;
-/**
- * Ordered tuple of dependency tags (and other constructor params)
- * inferred from a ServiceTag’s constructor.
- */
-type ServiceDepsTuple<T extends ServiceTag<TagId, unknown>> = InferConstructorDepsTuple<ConstructorParams<T>>;
-/**
- * Creates a service layer from any tag type (ServiceTag or ValueTag) with optional parameters.
- *
- * 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 (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.Service('LoggerService') {
- *   log(message: string) { console.log(message); }
- * }
- *
- * const loggerService = service(LoggerService, () => new LoggerService());
- * ```
- *
- * @example Service with dependencies
- * ```typescript
- * class DatabaseService extends Tag.Service('DatabaseService') {
- *   query() { return []; }
- * }
- *
- * class UserService extends Tag.Service('UserService') {
- *   constructor(private db: DatabaseService) {
- *     super();
- *   }
- *
- *   getUsers() { return this.db.query(); }
- * }
- *
- * 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>, CanonicalTag<T>>;
-/**
- * Specification for autoService.
- * Can be either a tuple of constructor parameters or an object with dependencies and finalizer.
- */
-type AutoServiceSpec<T extends ServiceTag<TagId, unknown>> = ServiceDepsTuple<T> | {
-  dependencies: ServiceDepsTuple<T>;
-  cleanup?: Finalizer<TagType<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 With finalizer for cleanup
- * ```typescript
- * 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;
- *     }
- *   }
- * }
- *
- * // Service with automatic cleanup
- * const dbService = autoService(
- *   DatabaseService,
- * 	 {
- * 		dependencies: ['postgresql://localhost:5432/mydb'],
- * 		cleanup: (service) => service.disconnect() // Finalizer for cleanup
- * 	 }
- * );
- * ```
- */
-declare function autoService<T extends ServiceTag<TagId, unknown>>(tag: T, spec: AutoServiceSpec<T>): Layer<ServiceDependencies<T>, CanonicalTag<T>>;
-
-//#endregion
-export { AnyLayer, AnyTag, CircularDependencyError, Container, ContainerDestroyedError, ContainerTags, DependencyAlreadyInstantiatedError, DependencyCreationError, DependencyFinalizationError, DependencyLifecycle, DependencySpec, Factory, Finalizer, IContainer, Inject, InjectSource, Layer, PromiseOrValue, ResolutionContext, SandlyError, Scope, ScopedContainer, ServiceDependencies, ServiceDepsTuple, ServiceTag, Tag, TagType, UnknownDependencyError, ValueTag, autoService, constant, dependency, layer, service };
+export { AnyLayer, AnyTag, BuilderTags, CircularDependencyError, Container, ContainerBuilder, ContainerDestroyedError, ContainerTags, DependencyCreationError, DependencyFinalizationError, DependencyLifecycle, DependencySpec, ErrorDump, Factory, Finalizer, IContainer, IContainerBuilder, Layer, Layer as LayerInterface, PromiseOrValue, ResolutionContext, SandlyError, Scope, ScopedContainer, ScopedContainerBuilder, ServiceTag, Tag, TagId, TagType, UnknownDependencyError, ValueTag };