effect 4.0.0-beta.69 → 4.0.0-beta.70

package/dist/Layer.d.ts

@@ -3,17 +3,28 @@
  * application. Services can be injected into effects via
  * `Effect.provideService`. Effects can require services via `Effect.service`.
  *
- * Layer can be thought of as recipes for producing bundles of services, given
- * their dependencies (other services).
+ * A layer is a recipe for producing services from their dependencies:
  *
- * Construction of services can be effectful and utilize resources that must be
- * acquired and safely released when the services are done being utilized.
+ * - `ROut` is what the layer provides.
+ * - `E` is what can fail while building the layer.
+ * - `RIn` is what the layer needs in order to build.
  *
- * By default layers are shared, meaning that if the same layer is used twice
- * the layer will only be allocated a single time.
+ * Normal application code should ask for services. Layer code should create
+ * services. The application entry point should provide the final layer once.
+ * Keeping this boundary clear makes programs easier to reuse with production,
+ * test, or mock implementations.
+ *
+ * Construction of services can be effectful and can acquire resources that must
+ * be safely released when the services are no longer used. For example, a layer
+ * can open a database pool during acquisition and close it in a finalizer.
+ *
+ * Layers are lazy: they do not build anything until they are provided to a
+ * program or explicitly built. By default layers are shared, meaning that if the
+ * same layer value is used twice, it is allocated only once and both users share
+ * the same service instance.
  *
  * Because of their excellent composition properties, layers are the idiomatic
- * way in Effect-TS to create services that depend on other services.
+ * way in Effect to create services that depend on other services.
  *
  * @since 2.0.0
  */
@@ -32,12 +43,13 @@ import type * as Types from "./Types.ts";
 import type * as Unify from "./Unify.ts";
 declare const TypeId = "~effect/Layer";
 /**
- * A Layer describes how to build one or more services for dependency injection.
+ * A `Layer` describes how to build one or more services for dependency injection.
+ *
+ * **Details**
  *
- * A Layer<ROut, E, RIn> represents:
- * - ROut: The services this layer provides
- * - E: The possible errors during layer construction
- * - RIn: The services this layer requires as dependencies
+ * A `Layer<ROut, E, RIn>` represents `ROut` as the services this layer
+ * provides, `E` as the possible errors during layer construction, and `RIn` as
+ * the services this layer requires as dependencies.
  *
  * @category models
  * @since 2.0.0
@@ -51,6 +63,8 @@ export interface Layer<in ROut, out E = never, out RIn = never> extends Variance
  * Type-level hook that allows `Layer` values to participate in `Unify`
  * inference.
  *
+ * **Details**
+ *
  * This is used by Effect's pipe and unification machinery to preserve the
  * provided services, error, and requirements of a `Layer`.
  *
@@ -85,12 +99,14 @@ export interface Variance<in ROut, out E, out RIn> {
     };
 }
 /**
- * A constraint interface for working with any Layer type.
+ * A type-level constraint for working with any `Layer` type.
  *
- * This interface is used to constrain generic types to Layer types
- * without specifying exact type parameters.
+ * **Details**
+ *
+ * This interface is used to constrain generic types to `Layer` values without
+ * specifying exact type parameters.
  *
- * @category type-level
+ * @category utility types
  * @since 3.9.0
  */
 export interface Any {
@@ -101,31 +117,34 @@ export interface Any {
     };
 }
 /**
- * Extracts the service dependencies (RIn) from a Layer type.
+ * Extracts the service requirements (`RIn`) from a `Layer` type.
  *
- * @category type-level
+ * @category utility types
  * @since 4.0.0
  */
 export type Services<T extends Any> = T extends infer L ? L extends Layer<infer _ROut, infer _E, infer _RIn> ? _RIn : never : never;
 /**
- * Extracts the error type (E) from a Layer type.
+ * Extracts the error type (`E`) from a `Layer` type.
  *
- * @category type-level
+ * @category utility types
  * @since 2.0.0
  */
 export type Error<T extends Any> = T extends Layer<infer _ROut, infer _E, infer _RIn> ? _E : never;
 /**
- * Extracts the service output type (ROut) from a Layer type.
+ * Extracts the service output type (`ROut`) from a `Layer` type.
  *
- * @category type-level
+ * @category utility types
  * @since 2.0.0
  */
 export type Success<T extends Any> = T extends Layer<infer _ROut, infer _E, infer _RIn> ? _ROut : never;
 declare const MemoMapTypeId = "~effect/Layer/MemoMap";
 /**
- * A MemoMap is used to memoize layer construction and ensure sharing of layers.
+ * A `MemoMap` is used to memoize layer construction and ensure sharing of
+ * layers.
  *
- * The MemoMap prevents duplicate construction of the same layer instance,
+ * **Details**
+ *
+ * The `MemoMap` prevents duplicate construction of the same layer instance,
  * enabling efficient resource sharing across layer dependencies.
  *
  * **Example** (Sharing layer construction with a memo map)
@@ -142,7 +161,7 @@ declare const MemoMapTypeId = "~effect/Layer/MemoMap";
  *   const memoMap = yield* Layer.makeMemoMap
  *   const scope = yield* Effect.scope
  *
- *   const dbLayer = Layer.succeed(Database)({
+ *   const dbLayer = Layer.succeed(Database, {
  *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  *   })
  *   const context = yield* Layer.buildWithMemoMap(dbLayer, memoMap, scope)
@@ -171,7 +190,7 @@ export interface MemoMap {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
- * const dbLayer = Layer.succeed(Database)({
+ * const dbLayer = Layer.succeed(Database, {
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  * })
  * const notALayer = { someProperty: "value" }
@@ -185,7 +204,10 @@ export interface MemoMap {
  */
 export declare const isLayer: (u: unknown) => u is Layer<unknown, unknown, unknown>;
 /**
- * Constructs a Layer from a function that uses a `MemoMap` and `Scope` to build the layer.
+ * Constructs a `Layer` from a function that uses a `MemoMap` and `Scope` to
+ * build the layer.
+ *
+ * **Details**
  *
  * The function receives a `MemoMap` for memoization and a `Scope` for resource management.
  * A child scope is created, and if the build fails, the child scope is closed.
@@ -213,8 +235,10 @@ export declare const isLayer: (u: unknown) => u is Layer<unknown, unknown, unkno
  */
 export declare const fromBuild: <ROut, E, RIn>(build: (memoMap: MemoMap, scope: Scope.Scope) => Effect<Context.Context<ROut>, E, RIn>) => Layer<ROut, E, RIn>;
 /**
- * Constructs a Layer from a function that uses a `MemoMap` and `Scope` to build the layer,
- * with automatic memoization.
+ * Constructs a `Layer` from a function that uses a `MemoMap` and `Scope` to
+ * build the layer, with automatic memoization.
+ *
+ * **Details**
  *
  * This is similar to `fromBuild` but provides automatic memoization of the layer construction.
  * The layer will be memoized based on the provided `MemoMap`.
@@ -258,7 +282,7 @@ export declare const fromBuildMemo: <ROut, E, RIn>(build: (memoMap: MemoMap, sco
  *   const memoMap = Layer.makeMemoMapUnsafe()
  *   const scope = yield* Effect.scope
  *
- *   const dbLayer = Layer.succeed(Database)({
+ *   const dbLayer = Layer.succeed(Database, {
  *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  *   })
  *   const context = yield* Layer.buildWithMemoMap(dbLayer, memoMap, scope)
@@ -296,7 +320,7 @@ export declare const forkMemoMapUnsafe: (parent: MemoMap) => MemoMap;
  *   const memoMap = yield* Layer.makeMemoMap
  *   const scope = yield* Effect.scope
  *
- *   const dbLayer = Layer.succeed(Database)({
+ *   const dbLayer = Layer.succeed(Database, {
  *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  *   })
  *   const context = yield* Layer.buildWithMemoMap(dbLayer, memoMap, scope)
@@ -321,6 +345,8 @@ declare const CurrentMemoMap_base: Context.ServiceClass<CurrentMemoMap, "effect/
 /**
  * A service reference for the current `MemoMap` used in layer construction.
  *
+ * **Details**
+ *
  * This service provides access to the current memoization map during layer building,
  * allowing layers to share memoized results.
  *
@@ -353,13 +379,13 @@ export declare class CurrentMemoMap extends CurrentMemoMap_base {
  *   const scope = yield* Effect.scope
  *
  *   // Build database layer with memoization
- *   const dbLayer = Layer.succeed(Database)({
+ *   const dbLayer = Layer.succeed(Database, {
  *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  *   })
  *   const dbContext = yield* Layer.buildWithMemoMap(dbLayer, memoMap, scope)
  *
  *   // Build logger layer with same memoization (reuses memo if same layer)
- *   const loggerLayer = Layer.succeed(Logger)({
+ *   const loggerLayer = Layer.succeed(Logger, {
  *     log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
  *   })
  *   const loggerContext = yield* Layer.buildWithMemoMap(
@@ -402,13 +428,13 @@ export declare const buildWithMemoMap: {
      *   const scope = yield* Effect.scope
      *
      *   // Build database layer with memoization
-     *   const dbLayer = Layer.succeed(Database)({
+     *   const dbLayer = Layer.succeed(Database, {
      *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
      *   })
      *   const dbContext = yield* Layer.buildWithMemoMap(dbLayer, memoMap, scope)
      *
      *   // Build logger layer with same memoization (reuses memo if same layer)
-     *   const loggerLayer = Layer.succeed(Logger)({
+     *   const loggerLayer = Layer.succeed(Logger, {
      *     log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
      *   })
      *   const loggerContext = yield* Layer.buildWithMemoMap(
@@ -451,13 +477,13 @@ export declare const buildWithMemoMap: {
      *   const scope = yield* Effect.scope
      *
      *   // Build database layer with memoization
-     *   const dbLayer = Layer.succeed(Database)({
+     *   const dbLayer = Layer.succeed(Database, {
      *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
      *   })
      *   const dbContext = yield* Layer.buildWithMemoMap(dbLayer, memoMap, scope)
      *
      *   // Build logger layer with same memoization (reuses memo if same layer)
-     *   const loggerLayer = Layer.succeed(Logger)({
+     *   const loggerLayer = Layer.succeed(Logger, {
      *     log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
      *   })
      *   const loggerContext = yield* Layer.buildWithMemoMap(
@@ -492,7 +518,7 @@ export declare const buildWithMemoMap: {
  *
  * // Build a layer to get its services
  * const program = Effect.gen(function*() {
- *   const dbLayer = Layer.succeed(Database)({
+ *   const dbLayer = Layer.succeed(Database, {
  *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  *   })
  *
@@ -530,7 +556,7 @@ export declare const build: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<
  * const program = Effect.gen(function*() {
  *   const scope = yield* Effect.scope
  *
- *   const dbLayer = Layer.effect(Database)(Effect.gen(function*() {
+ *   const dbLayer = Layer.effect(Database, Effect.gen(function*() {
  *     console.log("Initializing database...")
  *     yield* Scope.addFinalizer(
  *       scope,
@@ -572,7 +598,7 @@ export declare const buildWithScope: {
      * const program = Effect.gen(function*() {
      *   const scope = yield* Effect.scope
      *
-     *   const dbLayer = Layer.effect(Database)(Effect.gen(function*() {
+     *   const dbLayer = Layer.effect(Database, Effect.gen(function*() {
      *     console.log("Initializing database...")
      *     yield* Scope.addFinalizer(
      *       scope,
@@ -614,7 +640,7 @@ export declare const buildWithScope: {
      * const program = Effect.gen(function*() {
      *   const scope = yield* Effect.scope
      *
-     *   const dbLayer = Layer.effect(Database)(Effect.gen(function*() {
+     *   const dbLayer = Layer.effect(Database, Effect.gen(function*() {
      *     console.log("Initializing database...")
      *     yield* Scope.addFinalizer(
      *       scope,
@@ -638,9 +664,16 @@ export declare const buildWithScope: {
     <RIn, E, ROut>(self: Layer<ROut, E, RIn>, scope: Scope.Scope): Effect<Context.Context<ROut>, E, RIn>;
 };
 /**
- * Constructs a layer from the specified value.
+ * Constructs a layer that provides a single service from an already available
+ * value.
+ *
+ * **When to use**
  *
- * **Example** (Providing services from values)
+ * Use `succeed` when the service implementation is already constructed and does
+ * not need effectful acquisition. Use `sync` when the service should be created
+ * lazily during layer construction.
+ *
+ * **Example** (Creating a layer from a service implementation)
  *
  * ```ts
  * import { Context, Effect, Layer } from "effect"
@@ -649,42 +682,28 @@ export declare const buildWithScope: {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
- * class Logger extends Context.Service<Logger, {
- *   readonly log: (msg: string) => Effect.Effect<void>
- * }>()("Logger") {}
- *
- * // Create layers from concrete service implementations
- * const databaseLayer = Layer.succeed(Database)({
+ * const DatabaseLive = Layer.succeed(Database, {
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Query result: ${sql}`))
  * })
- *
- * const loggerLayer = Layer.succeed(Logger)({
- *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
- * })
- *
- * // Use the layers in a program
- * const program = Effect.gen(function*() {
- *   const database = yield* Database
- *   const logger = yield* Logger
- *
- *   yield* logger.log("Starting database query")
- *   const result = yield* database.query("SELECT * FROM users")
- *   yield* logger.log(`Query completed: ${result}`)
- *
- *   return result
- * }).pipe(
- *   Effect.provide(Layer.mergeAll(databaseLayer, loggerLayer))
- * )
  * ```
  *
+ * @see {@link sync} for constructing layers from lazy values
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const succeed: {
     /**
-     * Constructs a layer from the specified value.
+     * Constructs a layer that provides a single service from an already available
+     * value.
+     *
+     * **When to use**
      *
-     * **Example** (Providing services from values)
+     * Use `succeed` when the service implementation is already constructed and does
+     * not need effectful acquisition. Use `sync` when the service should be created
+     * lazily during layer construction.
+     *
+     * **Example** (Creating a layer from a service implementation)
      *
      * ```ts
      * import { Context, Effect, Layer } from "effect"
@@ -693,42 +712,28 @@ export declare const succeed: {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * class Logger extends Context.Service<Logger, {
-     *   readonly log: (msg: string) => Effect.Effect<void>
-     * }>()("Logger") {}
-     *
-     * // Create layers from concrete service implementations
-     * const databaseLayer = Layer.succeed(Database)({
+     * const DatabaseLive = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Query result: ${sql}`))
      * })
-     *
-     * const loggerLayer = Layer.succeed(Logger)({
-     *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
-     * })
-     *
-     * // Use the layers in a program
-     * const program = Effect.gen(function*() {
-     *   const database = yield* Database
-     *   const logger = yield* Logger
-     *
-     *   yield* logger.log("Starting database query")
-     *   const result = yield* database.query("SELECT * FROM users")
-     *   yield* logger.log(`Query completed: ${result}`)
-     *
-     *   return result
-     * }).pipe(
-     *   Effect.provide(Layer.mergeAll(databaseLayer, loggerLayer))
-     * )
      * ```
      *
+     * @see {@link sync} for constructing layers from lazy values
+     *
      * @category constructors
      * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>): (resource: S) => Layer<I>;
     /**
-     * Constructs a layer from the specified value.
+     * Constructs a layer that provides a single service from an already available
+     * value.
+     *
+     * **When to use**
      *
-     * **Example** (Providing services from values)
+     * Use `succeed` when the service implementation is already constructed and does
+     * not need effectful acquisition. Use `sync` when the service should be created
+     * lazily during layer construction.
+     *
+     * **Example** (Creating a layer from a service implementation)
      *
      * ```ts
      * import { Context, Effect, Layer } from "effect"
@@ -737,45 +742,32 @@ export declare const succeed: {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * class Logger extends Context.Service<Logger, {
-     *   readonly log: (msg: string) => Effect.Effect<void>
-     * }>()("Logger") {}
-     *
-     * // Create layers from concrete service implementations
-     * const databaseLayer = Layer.succeed(Database)({
+     * const DatabaseLive = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Query result: ${sql}`))
      * })
-     *
-     * const loggerLayer = Layer.succeed(Logger)({
-     *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
-     * })
-     *
-     * // Use the layers in a program
-     * const program = Effect.gen(function*() {
-     *   const database = yield* Database
-     *   const logger = yield* Logger
-     *
-     *   yield* logger.log("Starting database query")
-     *   const result = yield* database.query("SELECT * FROM users")
-     *   yield* logger.log(`Query completed: ${result}`)
-     *
-     *   return result
-     * }).pipe(
-     *   Effect.provide(Layer.mergeAll(databaseLayer, loggerLayer))
-     * )
      * ```
      *
+     * @see {@link sync} for constructing layers from lazy values
+     *
      * @category constructors
      * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>, resource: Types.NoInfer<S>): Layer<I>;
 };
 /**
- * Constructs a layer from the specified value, which must return one or more
- * services.
+ * Constructs a layer that provides all services in an already available
+ * `Context`.
  *
- * This is a more general version of `succeed` that allows you to provide multiple
- * services at once through a `Context`.
+ * **When to use**
+ *
+ * Use `succeedContext` when you already have a `Context` or need to provide
+ * multiple services at once. Use `succeed` when you only need to provide one
+ * service value.
+ *
+ * **Details**
+ *
+ * This is a more general version of `succeed` that allows you to provide
+ * multiple services at once through a `Context`.
  *
  * **Example** (Providing multiple services from a context)
  *
@@ -801,30 +793,50 @@ export declare const succeed: {
  * const layer = Layer.succeedContext(context)
  * ```
  *
+ * @see {@link succeed} for providing a single service from a value
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const succeedContext: <A>(context: Context.Context<A>) => Layer<A>;
 /**
- * A Layer that constructs an empty Context.
+ * An empty layer that provides no services, cannot fail, has no requirements,
+ * and performs no construction or finalization work.
  *
- * This layer provides no services and can be used as a neutral element
- * in layer composition or as a starting point for building layers.
+ * **When to use**
  *
- * **Example** (Creating an empty layer)
+ * Use `Layer.empty` as the no-op branch when conditionally composing layers.
+ * If you need to run an effect during layer construction while still providing
+ * no services, use `effectDiscard`.
+ *
+ * **Example** (Disabling optional lifecycle work)
  *
  * ```ts
- * import { Layer } from "effect"
+ * import { Console, Layer } from "effect"
+ *
+ * declare const flag: boolean
  *
- * const emptyLayer = Layer.empty
+ * const StartupLogLive = flag
+ *   ? Layer.effectDiscard(Console.log("application starting"))
+ *   : Layer.empty
  * ```
  *
+ * @see {@link effectDiscard} for running an effect while providing no services
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const empty: Layer<never>;
 /**
- * Lazily constructs a layer from the specified value.
+ * Lazily constructs a layer that provides a single service.
+ *
+ * **When to use**
+ *
+ * Use `sync` when the service can be created synchronously but should be
+ * deferred until the layer is built. Use `succeed` when the service value is
+ * already available.
+ *
+ * **Details**
  *
  * This is a lazy version of `succeed` where the service value is computed
  * synchronously only when the layer is built.
@@ -838,17 +850,27 @@ export declare const empty: Layer<never>;
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
- * const layer = Layer.sync(Database)(() => ({
+ * const layer = Layer.sync(Database, () => ({
  *   query: (sql: string) => Effect.succeed(`Query: ${sql}`)
  * }))
  * ```
  *
+ * @see {@link succeed} for constructing layers from static values
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const sync: {
     /**
-     * Lazily constructs a layer from the specified value.
+     * Lazily constructs a layer that provides a single service.
+     *
+     * **When to use**
+     *
+     * Use `sync` when the service can be created synchronously but should be
+     * deferred until the layer is built. Use `succeed` when the service value is
+     * already available.
+     *
+     * **Details**
      *
      * This is a lazy version of `succeed` where the service value is computed
      * synchronously only when the layer is built.
@@ -862,17 +884,27 @@ export declare const sync: {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * const layer = Layer.sync(Database)(() => ({
+     * const layer = Layer.sync(Database, () => ({
      *   query: (sql: string) => Effect.succeed(`Query: ${sql}`)
      * }))
      * ```
      *
+     * @see {@link succeed} for constructing layers from static values
+     *
      * @category constructors
      * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>): (evaluate: LazyArg<S>) => Layer<I>;
     /**
-     * Lazily constructs a layer from the specified value.
+     * Lazily constructs a layer that provides a single service.
+     *
+     * **When to use**
+     *
+     * Use `sync` when the service can be created synchronously but should be
+     * deferred until the layer is built. Use `succeed` when the service value is
+     * already available.
+     *
+     * **Details**
      *
      * This is a lazy version of `succeed` where the service value is computed
      * synchronously only when the layer is built.
@@ -886,21 +918,30 @@ export declare const sync: {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * const layer = Layer.sync(Database)(() => ({
+     * const layer = Layer.sync(Database, () => ({
      *   query: (sql: string) => Effect.succeed(`Query: ${sql}`)
      * }))
      * ```
      *
+     * @see {@link succeed} for constructing layers from static values
+     *
      * @category constructors
      * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>, evaluate: LazyArg<Types.NoInfer<S>>): Layer<I>;
 };
 /**
- * Lazily constructs a layer from the specified value, which must return one or more
- * services.
+ * Lazily constructs a layer that provides all services in a `Context`.
+ *
+ * **When to use**
  *
- * This is a lazy version of `succeedContext` where the Context is computed
+ * Use `syncContext` when multiple services can be created synchronously and
+ * should be deferred until the layer is built. Use `sync` when you only need to
+ * provide one service.
+ *
+ * **Details**
+ *
+ * This is a lazy version of `succeedContext` where the `Context` is computed
  * synchronously only when the layer is built.
  *
  * **Example** (Lazily providing a context)
@@ -919,15 +960,27 @@ export declare const sync: {
  * )
  * ```
  *
+ * @see {@link sync} for lazily providing a single service
+ * @see {@link succeedContext} for providing an already available context
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const syncContext: <A>(evaluate: LazyArg<Context.Context<A>>) => Layer<A>;
 /**
- * Constructs a layer from the specified scoped effect.
+ * Constructs a layer from an effect that produces a single service.
+ *
+ * **When to use**
+ *
+ * Use `effect` when constructing the service requires effects, dependencies, or
+ * scoped resource acquisition. Use `effectContext` when the effect produces
+ * multiple services in a `Context`, and `effectDiscard` when construction work
+ * should provide no services.
  *
- * This allows you to create a Layer from an Effect that produces a service.
- * The Effect is executed in the scope of the layer, allowing for proper
+ * **Details**
+ *
+ * This allows you to create a `Layer` from an `Effect` that produces a service.
+ * The `Effect` is executed in the scope of the layer, allowing for proper
  * resource management.
  *
  * **Example** (Creating a layer from an effect)
@@ -939,22 +992,34 @@ export declare const syncContext: <A>(evaluate: LazyArg<Context.Context<A>>) =>
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
- * const layer = Layer.effect(Database)(
+ * const layer = Layer.effect(Database,
  *   Effect.sync(() => ({
  *     query: (sql: string) => Effect.succeed(`Query: ${sql}`)
  *   }))
  * )
  * ```
  *
+ * @see {@link effectContext} for effectfully providing multiple services
+ * @see {@link effectDiscard} for running construction work without providing services
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const effect: {
     /**
-     * Constructs a layer from the specified scoped effect.
+     * Constructs a layer from an effect that produces a single service.
+     *
+     * **When to use**
+     *
+     * Use `effect` when constructing the service requires effects, dependencies, or
+     * scoped resource acquisition. Use `effectContext` when the effect produces
+     * multiple services in a `Context`, and `effectDiscard` when construction work
+     * should provide no services.
      *
-     * This allows you to create a Layer from an Effect that produces a service.
-     * The Effect is executed in the scope of the layer, allowing for proper
+     * **Details**
+     *
+     * This allows you to create a `Layer` from an `Effect` that produces a service.
+     * The `Effect` is executed in the scope of the layer, allowing for proper
      * resource management.
      *
      * **Example** (Creating a layer from an effect)
@@ -966,22 +1031,34 @@ export declare const effect: {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * const layer = Layer.effect(Database)(
+     * const layer = Layer.effect(Database,
      *   Effect.sync(() => ({
      *     query: (sql: string) => Effect.succeed(`Query: ${sql}`)
      *   }))
      * )
      * ```
      *
+     * @see {@link effectContext} for effectfully providing multiple services
+     * @see {@link effectDiscard} for running construction work without providing services
+     *
      * @category constructors
      * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>): <E, R>(effect: Effect<S, E, R>) => Layer<I, E, Exclude<R, Scope.Scope>>;
     /**
-     * Constructs a layer from the specified scoped effect.
+     * Constructs a layer from an effect that produces a single service.
+     *
+     * **When to use**
+     *
+     * Use `effect` when constructing the service requires effects, dependencies, or
+     * scoped resource acquisition. Use `effectContext` when the effect produces
+     * multiple services in a `Context`, and `effectDiscard` when construction work
+     * should provide no services.
      *
-     * This allows you to create a Layer from an Effect that produces a service.
-     * The Effect is executed in the scope of the layer, allowing for proper
+     * **Details**
+     *
+     * This allows you to create a `Layer` from an `Effect` that produces a service.
+     * The `Effect` is executed in the scope of the layer, allowing for proper
      * resource management.
      *
      * **Example** (Creating a layer from an effect)
@@ -993,24 +1070,34 @@ export declare const effect: {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * const layer = Layer.effect(Database)(
+     * const layer = Layer.effect(Database,
      *   Effect.sync(() => ({
      *     query: (sql: string) => Effect.succeed(`Query: ${sql}`)
      *   }))
      * )
      * ```
      *
+     * @see {@link effectContext} for effectfully providing multiple services
+     * @see {@link effectDiscard} for running construction work without providing services
+     *
      * @category constructors
      * @since 2.0.0
      */
     <I, S, E, R>(service: Context.Key<I, S>, effect: Effect<Types.NoInfer<S>, E, R>): Layer<I, E, Exclude<R, Scope.Scope>>;
 };
 /**
- * Constructs a layer from the specified scoped effect, which must return one
- * or more services.
+ * Constructs a layer from an effect that produces all services in a `Context`.
+ *
+ * **When to use**
+ *
+ * Use `effectContext` when effectful construction needs to provide multiple
+ * services at once. Use `effect` when the effect produces one service value.
  *
- * This allows you to create a Layer from an effectful computation that returns
- * multiple services. The Effect is executed in the scope of the layer.
+ * **Details**
+ *
+ * This allows you to create a `Layer` from an effectful computation that
+ * returns multiple services. The `Effect` is executed in the scope of the
+ * layer.
  *
  * **Example** (Creating a layer from an effectful context)
  *
@@ -1029,12 +1116,17 @@ export declare const effect: {
  * )
  * ```
  *
+ * @see {@link effect} for effectfully providing a single service
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const effectContext: <A, E, R>(effect: Effect<Context.Context<A>, E, R>) => Layer<A, E, Exclude<R, Scope.Scope>>;
 /**
- * Constructs a layer from the specified scoped effect.
+ * Constructs a layer from an effect, discarding its value and providing no
+ * services.
+ *
+ * **When to use**
  *
  * This is useful when you want to run an Effect for its side effects during
  * layer construction, but don't need to provide any services.
@@ -1051,6 +1143,8 @@ export declare const effectContext: <A, E, R>(effect: Effect<Context.Context<A>,
  * )
  * ```
  *
+ * @see {@link empty} for a no-op layer that performs no construction work
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1058,6 +1152,8 @@ export declare const effectDiscard: <X, E, R>(effect: Effect<X, E, R>) => Layer<
 /**
  * Lazily constructs a layer using the specified factory.
  *
+ * **Details**
+ *
  * The factory is evaluated only when the suspended layer is first built, and
  * the result is memoized with normal layer sharing semantics.
  *
@@ -1072,8 +1168,8 @@ export declare const effectDiscard: <X, E, R>(effect: Effect<X, E, R>) => Layer<
  *
  * const layer = Layer.suspend(() =>
  *   useProd
- *     ? Layer.succeed(Config)("https://api.example.com")
- *     : Layer.succeed(Config)("http://localhost:3000")
+ *     ? Layer.succeed(Config, "https://api.example.com")
+ *     : Layer.succeed(Config, "http://localhost:3000")
  * )
  * ```
  *
@@ -1082,11 +1178,17 @@ export declare const effectDiscard: <X, E, R>(effect: Effect<X, E, R>) => Layer<
  */
 export declare const suspend: <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>) => Layer<A, E, R>;
 /**
- * Unwraps a Layer from an Effect, flattening the nested structure.
+ * Unwraps a `Layer` from an `Effect`, flattening the nested structure.
+ *
+ * **When to use**
  *
- * This is useful when you have an Effect that produces a Layer, and you want to
- * use that Layer directly. The resulting Layer will have the combined error and
- * dependency types from both the outer Effect and the inner Layer.
+ * Use this when you have an `Effect` that produces a `Layer` and you want to
+ * use that layer directly.
+ *
+ * **Details**
+ *
+ * The resulting Layer will have the combined error and dependency types from
+ * both the outer Effect and the inner Layer.
  *
  * **Example** (Unwrapping an effectful layer)
  *
@@ -1098,7 +1200,7 @@ export declare const suspend: <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>) => La
  * }>()("Database") {}
  *
  * const layerEffect = Effect.succeed(
- *   Layer.succeed(Database)({ query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result")) })
+ *   Layer.succeed(Database, { query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result")) })
  * )
  *
  * const unwrappedLayer = Layer.unwrap(layerEffect)
@@ -1109,10 +1211,20 @@ export declare const suspend: <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>) => La
  */
 export declare const unwrap: <A, E1, R1, E, R>(self: Effect<Layer<A, E1, R1>, E, R>) => Layer<A, E | E1, R1 | Exclude<R, Scope.Scope>>;
 /**
- * Combines all the provided layers concurrently, creating a new layer with merged input, error, and output types.
+ * Combines all the provided layers concurrently, creating a new layer with
+ * merged input, error, and output types.
+ *
+ * **When to use**
+ *
+ * Use this when you need to combine multiple independent layers.
+ *
+ * **Details**
  *
  * All layers are built concurrently, and their outputs are merged into a single layer.
- * This is useful when you need to combine multiple independent layers.
+ *
+ * If multiple merged layers depend on the same layer value, that dependency is
+ * shared by default. Reuse a named layer value when you want services to share
+ * the same resource, such as one database pool.
  *
  * **Example** (Merging independent layers)
  *
@@ -1127,25 +1239,36 @@ export declare const unwrap: <A, E1, R1, E, R>(self: Effect<Layer<A, E1, R1>, E,
  *   readonly log: (msg: string) => Effect.Effect<void>
  * }>()("Logger") {}
  *
- * const dbLayer = Layer.succeed(Database)({
+ * const dbLayer = Layer.succeed(Database, {
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  * })
- * const loggerLayer = Layer.succeed(Logger)({
+ * const loggerLayer = Layer.succeed(Logger, {
  *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
  * })
  *
  * const mergedLayer = Layer.mergeAll(dbLayer, loggerLayer)
  * ```
  *
+ * @see {@link merge} for merging one layer with another layer or array
+ *
  * @category zipping
  * @since 2.0.0
  */
 export declare const mergeAll: <Layers extends [Layer<never, any, any>, ...Array<Layer<never, any, any>>]>(...layers: Layers) => Layer<Success<Layers[number]>, Error<Layers[number]>, Services<Layers[number]>>;
 /**
- * Merges this layer with the specified layer concurrently, producing a new layer with combined input and output types.
+ * Merges this layer with another layer concurrently, producing a new layer with
+ * combined input, error, and output types.
+ *
+ * **When to use**
+ *
+ * Use `merge` when composing from an existing layer in a pipeline. Use
+ * `mergeAll` when you already have all layers as separate arguments.
  *
- * This is a binary version of `mergeAll` that merges exactly two layers or one layer with an array of layers.
- * The layers are built concurrently and their outputs are combined.
+ * **Details**
+ *
+ * This is a binary version of `mergeAll` that merges exactly two layers or one
+ * layer with an array of layers. The layers are built concurrently and their
+ * outputs are combined.
  *
  * **Example** (Merging two layers)
  *
@@ -1160,25 +1283,36 @@ export declare const mergeAll: <Layers extends [Layer<never, any, any>, ...Array
  *   readonly log: (msg: string) => Effect.Effect<void>
  * }>()("Logger") {}
  *
- * const dbLayer = Layer.succeed(Database)({
+ * const dbLayer = Layer.succeed(Database, {
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  * })
- * const loggerLayer = Layer.succeed(Logger)({
+ * const loggerLayer = Layer.succeed(Logger, {
  *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
  * })
  *
  * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
  * ```
  *
+ * @see {@link mergeAll} for merging several layers at once
+ *
  * @category zipping
  * @since 2.0.0
  */
 export declare const merge: {
     /**
-     * Merges this layer with the specified layer concurrently, producing a new layer with combined input and output types.
+     * Merges this layer with another layer concurrently, producing a new layer with
+     * combined input, error, and output types.
+     *
+     * **When to use**
      *
-     * This is a binary version of `mergeAll` that merges exactly two layers or one layer with an array of layers.
-     * The layers are built concurrently and their outputs are combined.
+     * Use `merge` when composing from an existing layer in a pipeline. Use
+     * `mergeAll` when you already have all layers as separate arguments.
+     *
+     * **Details**
+     *
+     * This is a binary version of `mergeAll` that merges exactly two layers or one
+     * layer with an array of layers. The layers are built concurrently and their
+     * outputs are combined.
      *
      * **Example** (Merging two layers)
      *
@@ -1193,25 +1327,36 @@ export declare const merge: {
      *   readonly log: (msg: string) => Effect.Effect<void>
      * }>()("Logger") {}
      *
-     * const dbLayer = Layer.succeed(Database)({
+     * const dbLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
      * })
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
      * })
      *
      * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
      * ```
      *
+     * @see {@link mergeAll} for merging several layers at once
+     *
      * @category zipping
      * @since 2.0.0
      */
     <RIn, E, ROut>(that: Layer<ROut, E, RIn>): <RIn2, E2, ROut2>(self: Layer<ROut2, E2, RIn2>) => Layer<ROut | ROut2, E | E2, RIn | RIn2>;
     /**
-     * Merges this layer with the specified layer concurrently, producing a new layer with combined input and output types.
+     * Merges this layer with another layer concurrently, producing a new layer with
+     * combined input, error, and output types.
+     *
+     * **When to use**
      *
-     * This is a binary version of `mergeAll` that merges exactly two layers or one layer with an array of layers.
-     * The layers are built concurrently and their outputs are combined.
+     * Use `merge` when composing from an existing layer in a pipeline. Use
+     * `mergeAll` when you already have all layers as separate arguments.
+     *
+     * **Details**
+     *
+     * This is a binary version of `mergeAll` that merges exactly two layers or one
+     * layer with an array of layers. The layers are built concurrently and their
+     * outputs are combined.
      *
      * **Example** (Merging two layers)
      *
@@ -1226,25 +1371,36 @@ export declare const merge: {
      *   readonly log: (msg: string) => Effect.Effect<void>
      * }>()("Logger") {}
      *
-     * const dbLayer = Layer.succeed(Database)({
+     * const dbLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
      * })
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
      * })
      *
      * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
      * ```
      *
+     * @see {@link mergeAll} for merging several layers at once
+     *
      * @category zipping
      * @since 2.0.0
      */
     <const Layers extends [Any, ...Array<Any>]>(that: Layers): <A, E, R>(self: Layer<A, E, R>) => Layer<A | Success<Layers[number]>, E | Error<Layers[number]>, Services<Layers[number]> | R>;
     /**
-     * Merges this layer with the specified layer concurrently, producing a new layer with combined input and output types.
+     * Merges this layer with another layer concurrently, producing a new layer with
+     * combined input, error, and output types.
      *
-     * This is a binary version of `mergeAll` that merges exactly two layers or one layer with an array of layers.
-     * The layers are built concurrently and their outputs are combined.
+     * **When to use**
+     *
+     * Use `merge` when composing from an existing layer in a pipeline. Use
+     * `mergeAll` when you already have all layers as separate arguments.
+     *
+     * **Details**
+     *
+     * This is a binary version of `mergeAll` that merges exactly two layers or one
+     * layer with an array of layers. The layers are built concurrently and their
+     * outputs are combined.
      *
      * **Example** (Merging two layers)
      *
@@ -1259,25 +1415,36 @@ export declare const merge: {
      *   readonly log: (msg: string) => Effect.Effect<void>
      * }>()("Logger") {}
      *
-     * const dbLayer = Layer.succeed(Database)({
+     * const dbLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
      * })
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
      * })
      *
      * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
      * ```
      *
+     * @see {@link mergeAll} for merging several layers at once
+     *
      * @category zipping
      * @since 2.0.0
      */
     <RIn2, E2, ROut2, RIn, E, ROut>(self: Layer<ROut2, E2, RIn2>, that: Layer<ROut, E, RIn>): Layer<ROut | ROut2, E | E2, RIn | RIn2>;
     /**
-     * Merges this layer with the specified layer concurrently, producing a new layer with combined input and output types.
+     * Merges this layer with another layer concurrently, producing a new layer with
+     * combined input, error, and output types.
+     *
+     * **When to use**
+     *
+     * Use `merge` when composing from an existing layer in a pipeline. Use
+     * `mergeAll` when you already have all layers as separate arguments.
      *
-     * This is a binary version of `mergeAll` that merges exactly two layers or one layer with an array of layers.
-     * The layers are built concurrently and their outputs are combined.
+     * **Details**
+     *
+     * This is a binary version of `mergeAll` that merges exactly two layers or one
+     * layer with an array of layers. The layers are built concurrently and their
+     * outputs are combined.
      *
      * **Example** (Merging two layers)
      *
@@ -1292,25 +1459,37 @@ export declare const merge: {
      *   readonly log: (msg: string) => Effect.Effect<void>
      * }>()("Logger") {}
      *
-     * const dbLayer = Layer.succeed(Database)({
+     * const dbLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
      * })
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
      * })
      *
      * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
      * ```
      *
+     * @see {@link mergeAll} for merging several layers at once
+     *
      * @category zipping
      * @since 2.0.0
      */
     <A, E, R, const Layers extends [Any, ...Array<Any>]>(self: Layer<A, E, R>, that: Layers): Layer<A | Success<Layers[number]>, E | Error<Layers[number]>, Services<Layers[number]> | R>;
 };
 /**
- * Feeds the output services of this builder into the input of the specified
- * builder, resulting in a new builder with the inputs of this builder as
- * well as any leftover inputs, and the outputs of the specified builder.
+ * Feeds the output services of the dependency layer into the requirements of
+ * this layer, returning a layer that only provides the services from this layer.
+ *
+ * **When to use**
+ *
+ * Use `provide` when the dependency layer is an implementation detail of the
+ * layer being built and should not be exposed to callers. Use `provideMerge`
+ * when callers should also receive the dependency services.
+ *
+ * **Details**
+ *
+ * In `serviceLayer.pipe(Layer.provide(dependencyLayer))`, the dependency layer is
+ * built first and is used to satisfy the requirements of `serviceLayer`.
  *
  * **Example** (Providing layer dependencies)
  *
@@ -1333,16 +1512,16 @@ export declare const merge: {
  * }>()("Logger") {}
  *
  * // Create dependency layers
- * const databaseLayer = Layer.succeed(Database)({
+ * const databaseLayer = Layer.succeed(Database, {
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
  * })
  *
- * const loggerLayer = Layer.succeed(Logger)({
+ * const loggerLayer = Layer.succeed(Logger, {
  *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
  * })
  *
  * // UserService depends on Database and Logger
- * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+ * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
  *   const database = yield* Database
  *   const logger = yield* Logger
  *
@@ -1371,14 +1550,26 @@ export declare const merge: {
  * )
  * ```
  *
+ * @see {@link provideMerge} for retaining the dependency services
+ *
  * @category utils
  * @since 2.0.0
  */
 export declare const provide: {
     /**
-     * Feeds the output services of this builder into the input of the specified
-     * builder, resulting in a new builder with the inputs of this builder as
-     * well as any leftover inputs, and the outputs of the specified builder.
+     * Feeds the output services of the dependency layer into the requirements of
+     * this layer, returning a layer that only provides the services from this layer.
+     *
+     * **When to use**
+     *
+     * Use `provide` when the dependency layer is an implementation detail of the
+     * layer being built and should not be exposed to callers. Use `provideMerge`
+     * when callers should also receive the dependency services.
+     *
+     * **Details**
+     *
+     * In `serviceLayer.pipe(Layer.provide(dependencyLayer))`, the dependency layer is
+     * built first and is used to satisfy the requirements of `serviceLayer`.
      *
      * **Example** (Providing layer dependencies)
      *
@@ -1401,16 +1592,16 @@ export declare const provide: {
      * }>()("Logger") {}
      *
      * // Create dependency layers
-     * const databaseLayer = Layer.succeed(Database)({
+     * const databaseLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
      * })
      *
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
      * })
      *
      * // UserService depends on Database and Logger
-     * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+     * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
      *   const database = yield* Database
      *   const logger = yield* Logger
      *
@@ -1439,14 +1630,26 @@ export declare const provide: {
      * )
      * ```
      *
+     * @see {@link provideMerge} for retaining the dependency services
+     *
      * @category utils
      * @since 2.0.0
      */
     <RIn, E, ROut>(that: Layer<ROut, E, RIn>): <RIn2, E2, ROut2>(self: Layer<ROut2, E2, RIn2>) => Layer<ROut2, E | E2, RIn | Exclude<RIn2, ROut>>;
     /**
-     * Feeds the output services of this builder into the input of the specified
-     * builder, resulting in a new builder with the inputs of this builder as
-     * well as any leftover inputs, and the outputs of the specified builder.
+     * Feeds the output services of the dependency layer into the requirements of
+     * this layer, returning a layer that only provides the services from this layer.
+     *
+     * **When to use**
+     *
+     * Use `provide` when the dependency layer is an implementation detail of the
+     * layer being built and should not be exposed to callers. Use `provideMerge`
+     * when callers should also receive the dependency services.
+     *
+     * **Details**
+     *
+     * In `serviceLayer.pipe(Layer.provide(dependencyLayer))`, the dependency layer is
+     * built first and is used to satisfy the requirements of `serviceLayer`.
      *
      * **Example** (Providing layer dependencies)
      *
@@ -1469,16 +1672,16 @@ export declare const provide: {
      * }>()("Logger") {}
      *
      * // Create dependency layers
-     * const databaseLayer = Layer.succeed(Database)({
+     * const databaseLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
      * })
      *
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
      * })
      *
      * // UserService depends on Database and Logger
-     * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+     * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
      *   const database = yield* Database
      *   const logger = yield* Logger
      *
@@ -1507,14 +1710,26 @@ export declare const provide: {
      * )
      * ```
      *
+     * @see {@link provideMerge} for retaining the dependency services
+     *
      * @category utils
      * @since 2.0.0
      */
     <const Layers extends [Any, ...Array<Any>]>(that: Layers): <A, E, R>(self: Layer<A, E, R>) => Layer<A, E | Error<Layers[number]>, Services<Layers[number]> | Exclude<R, Success<Layers[number]>>>;
     /**
-     * Feeds the output services of this builder into the input of the specified
-     * builder, resulting in a new builder with the inputs of this builder as
-     * well as any leftover inputs, and the outputs of the specified builder.
+     * Feeds the output services of the dependency layer into the requirements of
+     * this layer, returning a layer that only provides the services from this layer.
+     *
+     * **When to use**
+     *
+     * Use `provide` when the dependency layer is an implementation detail of the
+     * layer being built and should not be exposed to callers. Use `provideMerge`
+     * when callers should also receive the dependency services.
+     *
+     * **Details**
+     *
+     * In `serviceLayer.pipe(Layer.provide(dependencyLayer))`, the dependency layer is
+     * built first and is used to satisfy the requirements of `serviceLayer`.
      *
      * **Example** (Providing layer dependencies)
      *
@@ -1537,16 +1752,16 @@ export declare const provide: {
      * }>()("Logger") {}
      *
      * // Create dependency layers
-     * const databaseLayer = Layer.succeed(Database)({
+     * const databaseLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
      * })
      *
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
      * })
      *
      * // UserService depends on Database and Logger
-     * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+     * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
      *   const database = yield* Database
      *   const logger = yield* Logger
      *
@@ -1575,14 +1790,26 @@ export declare const provide: {
      * )
      * ```
      *
+     * @see {@link provideMerge} for retaining the dependency services
+     *
      * @category utils
      * @since 2.0.0
      */
     <RIn2, E2, ROut2, RIn, E, ROut>(self: Layer<ROut2, E2, RIn2>, that: Layer<ROut, E, RIn>): Layer<ROut2, E | E2, RIn | Exclude<RIn2, ROut>>;
     /**
-     * Feeds the output services of this builder into the input of the specified
-     * builder, resulting in a new builder with the inputs of this builder as
-     * well as any leftover inputs, and the outputs of the specified builder.
+     * Feeds the output services of the dependency layer into the requirements of
+     * this layer, returning a layer that only provides the services from this layer.
+     *
+     * **When to use**
+     *
+     * Use `provide` when the dependency layer is an implementation detail of the
+     * layer being built and should not be exposed to callers. Use `provideMerge`
+     * when callers should also receive the dependency services.
+     *
+     * **Details**
+     *
+     * In `serviceLayer.pipe(Layer.provide(dependencyLayer))`, the dependency layer is
+     * built first and is used to satisfy the requirements of `serviceLayer`.
      *
      * **Example** (Providing layer dependencies)
      *
@@ -1605,16 +1832,16 @@ export declare const provide: {
      * }>()("Logger") {}
      *
      * // Create dependency layers
-     * const databaseLayer = Layer.succeed(Database)({
+     * const databaseLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
      * })
      *
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
      * })
      *
      * // UserService depends on Database and Logger
-     * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+     * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
      *   const database = yield* Database
      *   const logger = yield* Logger
      *
@@ -1643,15 +1870,23 @@ export declare const provide: {
      * )
      * ```
      *
+     * @see {@link provideMerge} for retaining the dependency services
+     *
      * @category utils
      * @since 2.0.0
      */
     <A, E, R, const Layers extends [Any, ...Array<Any>]>(self: Layer<A, E, R>, that: Layers): Layer<A, E | Error<Layers[number]>, Services<Layers[number]> | Exclude<R, Success<Layers[number]>>>;
 };
 /**
- * Feeds the output services of this layer into the input of the specified
- * layer, resulting in a new layer with the inputs of this layer, and the
- * outputs of both layers.
+ * Feeds the output services of the dependency layer into the requirements of
+ * this layer, returning a layer that provides both sets of services.
+ *
+ * **When to use**
+ *
+ * Use this when callers need access to both the service being built and the
+ * dependency used to build it, such as a health check that needs both a
+ * repository and its database. Prefer `provide` when the dependency should stay
+ * private.
  *
  * **Example** (Providing dependencies while retaining services)
  *
@@ -1674,16 +1909,16 @@ export declare const provide: {
  * }>()("UserService") {}
  *
  * // Create dependency layers
- * const databaseLayer = Layer.succeed(Database)({
+ * const databaseLayer = Layer.succeed(Database, {
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
  * })
  *
- * const loggerLayer = Layer.succeed(Logger)({
+ * const loggerLayer = Layer.succeed(Logger, {
  *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
  * })
  *
  * // UserService depends on Database and Logger
- * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+ * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
  *   const database = yield* Database
  *   const logger = yield* Logger
  *
@@ -1718,14 +1953,22 @@ export declare const provide: {
  * )
  * ```
  *
+ * @see {@link provide} for keeping dependency services private
+ *
  * @category utils
  * @since 2.0.0
  */
 export declare const provideMerge: {
     /**
-     * Feeds the output services of this layer into the input of the specified
-     * layer, resulting in a new layer with the inputs of this layer, and the
-     * outputs of both layers.
+     * Feeds the output services of the dependency layer into the requirements of
+     * this layer, returning a layer that provides both sets of services.
+     *
+     * **When to use**
+     *
+     * Use this when callers need access to both the service being built and the
+     * dependency used to build it, such as a health check that needs both a
+     * repository and its database. Prefer `provide` when the dependency should stay
+     * private.
      *
      * **Example** (Providing dependencies while retaining services)
      *
@@ -1748,16 +1991,16 @@ export declare const provideMerge: {
      * }>()("UserService") {}
      *
      * // Create dependency layers
-     * const databaseLayer = Layer.succeed(Database)({
+     * const databaseLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
      * })
      *
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
      * })
      *
      * // UserService depends on Database and Logger
-     * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+     * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
      *   const database = yield* Database
      *   const logger = yield* Logger
      *
@@ -1792,14 +2035,22 @@ export declare const provideMerge: {
      * )
      * ```
      *
+     * @see {@link provide} for keeping dependency services private
+     *
      * @category utils
      * @since 2.0.0
      */
     <RIn, E, ROut>(that: Layer<ROut, E, RIn>): <RIn2, E2, ROut2>(self: Layer<ROut2, E2, RIn2>) => Layer<ROut | ROut2, E | E2, RIn | Exclude<RIn2, ROut>>;
     /**
-     * Feeds the output services of this layer into the input of the specified
-     * layer, resulting in a new layer with the inputs of this layer, and the
-     * outputs of both layers.
+     * Feeds the output services of the dependency layer into the requirements of
+     * this layer, returning a layer that provides both sets of services.
+     *
+     * **When to use**
+     *
+     * Use this when callers need access to both the service being built and the
+     * dependency used to build it, such as a health check that needs both a
+     * repository and its database. Prefer `provide` when the dependency should stay
+     * private.
      *
      * **Example** (Providing dependencies while retaining services)
      *
@@ -1822,16 +2073,16 @@ export declare const provideMerge: {
      * }>()("UserService") {}
      *
      * // Create dependency layers
-     * const databaseLayer = Layer.succeed(Database)({
+     * const databaseLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
      * })
      *
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
      * })
      *
      * // UserService depends on Database and Logger
-     * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+     * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
      *   const database = yield* Database
      *   const logger = yield* Logger
      *
@@ -1866,14 +2117,22 @@ export declare const provideMerge: {
      * )
      * ```
      *
+     * @see {@link provide} for keeping dependency services private
+     *
      * @category utils
      * @since 2.0.0
      */
     <const Layers extends [Any, ...Array<Any>]>(that: Layers): <A, E, R>(self: Layer<A, E, R>) => Layer<A | Success<Layers[number]>, E | Error<Layers[number]>, Services<Layers[number]> | Exclude<R, Success<Layers[number]>>>;
     /**
-     * Feeds the output services of this layer into the input of the specified
-     * layer, resulting in a new layer with the inputs of this layer, and the
-     * outputs of both layers.
+     * Feeds the output services of the dependency layer into the requirements of
+     * this layer, returning a layer that provides both sets of services.
+     *
+     * **When to use**
+     *
+     * Use this when callers need access to both the service being built and the
+     * dependency used to build it, such as a health check that needs both a
+     * repository and its database. Prefer `provide` when the dependency should stay
+     * private.
      *
      * **Example** (Providing dependencies while retaining services)
      *
@@ -1896,16 +2155,16 @@ export declare const provideMerge: {
      * }>()("UserService") {}
      *
      * // Create dependency layers
-     * const databaseLayer = Layer.succeed(Database)({
+     * const databaseLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
      * })
      *
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
      * })
      *
      * // UserService depends on Database and Logger
-     * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+     * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
      *   const database = yield* Database
      *   const logger = yield* Logger
      *
@@ -1940,14 +2199,22 @@ export declare const provideMerge: {
      * )
      * ```
      *
+     * @see {@link provide} for keeping dependency services private
+     *
      * @category utils
      * @since 2.0.0
      */
     <RIn2, E2, ROut2, RIn, E, ROut>(self: Layer<ROut2, E2, RIn2>, that: Layer<ROut, E, RIn>): Layer<ROut | ROut2, E | E2, RIn | Exclude<RIn2, ROut>>;
     /**
-     * Feeds the output services of this layer into the input of the specified
-     * layer, resulting in a new layer with the inputs of this layer, and the
-     * outputs of both layers.
+     * Feeds the output services of the dependency layer into the requirements of
+     * this layer, returning a layer that provides both sets of services.
+     *
+     * **When to use**
+     *
+     * Use this when callers need access to both the service being built and the
+     * dependency used to build it, such as a health check that needs both a
+     * repository and its database. Prefer `provide` when the dependency should stay
+     * private.
      *
      * **Example** (Providing dependencies while retaining services)
      *
@@ -1970,16 +2237,16 @@ export declare const provideMerge: {
      * }>()("UserService") {}
      *
      * // Create dependency layers
-     * const databaseLayer = Layer.succeed(Database)({
+     * const databaseLayer = Layer.succeed(Database, {
      *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
      * })
      *
-     * const loggerLayer = Layer.succeed(Logger)({
+     * const loggerLayer = Layer.succeed(Logger, {
      *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
      * })
      *
      * // UserService depends on Database and Logger
-     * const userServiceLayer = Layer.effect(UserService)(Effect.gen(function*() {
+     * const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
      *   const database = yield* Database
      *   const logger = yield* Logger
      *
@@ -2014,6 +2281,8 @@ export declare const provideMerge: {
      * )
      * ```
      *
+     * @see {@link provide} for keeping dependency services private
+     *
      * @category utils
      * @since 2.0.0
      */
@@ -2041,7 +2310,7 @@ export declare const provideMerge: {
  * }>()("Logger") {}
  *
  * // Base config layer
- * const configLayer = Layer.succeed(Config)({
+ * const configLayer = Layer.succeed(Config, {
  *   dbUrl: "postgres://localhost:5432/mydb",
  *   logLevel: "debug"
  * })
@@ -2052,7 +2321,7 @@ export declare const provideMerge: {
  *     const config = Context.get(context, Config)
  *
  *     // Create database layer based on config
- *     const dbLayer = Layer.succeed(Database)({
+ *     const dbLayer = Layer.succeed(Database, {
  *       query: Effect.fn("Database.query")((sql: string) =>
  *         Effect.succeed(
  *           `Querying ${config.dbUrl}: ${sql}`
@@ -2060,7 +2329,7 @@ export declare const provideMerge: {
  *     })
  *
  *     // Create logger layer based on config
- *     const loggerLayer = Layer.succeed(Logger)({
+ *     const loggerLayer = Layer.succeed(Logger, {
  *       log: Effect.fn("Logger.log")((msg: string) =>
  *         config.logLevel === "debug"
  *           ? Effect.sync(() => console.log(`[DEBUG] ${msg}`))
@@ -2113,7 +2382,7 @@ export declare const flatMap: {
      * }>()("Logger") {}
      *
      * // Base config layer
-     * const configLayer = Layer.succeed(Config)({
+     * const configLayer = Layer.succeed(Config, {
      *   dbUrl: "postgres://localhost:5432/mydb",
      *   logLevel: "debug"
      * })
@@ -2124,7 +2393,7 @@ export declare const flatMap: {
      *     const config = Context.get(context, Config)
      *
      *     // Create database layer based on config
-     *     const dbLayer = Layer.succeed(Database)({
+     *     const dbLayer = Layer.succeed(Database, {
      *       query: Effect.fn("Database.query")((sql: string) =>
      *         Effect.succeed(
      *           `Querying ${config.dbUrl}: ${sql}`
@@ -2132,7 +2401,7 @@ export declare const flatMap: {
      *     })
      *
      *     // Create logger layer based on config
-     *     const loggerLayer = Layer.succeed(Logger)({
+     *     const loggerLayer = Layer.succeed(Logger, {
      *       log: Effect.fn("Logger.log")((msg: string) =>
      *         config.logLevel === "debug"
      *           ? Effect.sync(() => console.log(`[DEBUG] ${msg}`))
@@ -2185,7 +2454,7 @@ export declare const flatMap: {
      * }>()("Logger") {}
      *
      * // Base config layer
-     * const configLayer = Layer.succeed(Config)({
+     * const configLayer = Layer.succeed(Config, {
      *   dbUrl: "postgres://localhost:5432/mydb",
      *   logLevel: "debug"
      * })
@@ -2196,7 +2465,7 @@ export declare const flatMap: {
      *     const config = Context.get(context, Config)
      *
      *     // Create database layer based on config
-     *     const dbLayer = Layer.succeed(Database)({
+     *     const dbLayer = Layer.succeed(Database, {
      *       query: Effect.fn("Database.query")((sql: string) =>
      *         Effect.succeed(
      *           `Querying ${config.dbUrl}: ${sql}`
@@ -2204,7 +2473,7 @@ export declare const flatMap: {
      *     })
      *
      *     // Create logger layer based on config
-     *     const loggerLayer = Layer.succeed(Logger)({
+     *     const loggerLayer = Layer.succeed(Logger, {
      *       log: Effect.fn("Logger.log")((msg: string) =>
      *         config.logLevel === "debug"
      *           ? Effect.sync(() => console.log(`[DEBUG] ${msg}`))
@@ -2239,6 +2508,11 @@ export declare const flatMap: {
 /**
  * Performs the specified effect if this layer succeeds.
  *
+ * **Details**
+ *
+ * The callback receives the services produced by this layer. Its result is
+ * discarded, and the original layer output is preserved.
+ *
  * @category sequencing
  * @since 2.0.0
  */
@@ -2246,6 +2520,11 @@ export declare const tap: {
     /**
      * Performs the specified effect if this layer succeeds.
      *
+     * **Details**
+     *
+     * The callback receives the services produced by this layer. Its result is
+     * discarded, and the original layer output is preserved.
+     *
      * @category sequencing
      * @since 2.0.0
      */
@@ -2253,6 +2532,11 @@ export declare const tap: {
     /**
      * Performs the specified effect if this layer succeeds.
      *
+     * **Details**
+     *
+     * The callback receives the services produced by this layer. Its result is
+     * discarded, and the original layer output is preserved.
+     *
      * @category sequencing
      * @since 2.0.0
      */
@@ -2261,6 +2545,12 @@ export declare const tap: {
 /**
  * Performs the specified effect if this layer fails.
  *
+ * **Details**
+ *
+ * The callback receives the typed error. If the callback succeeds, the layer
+ * still fails with the original error; if the callback fails, that failure is
+ * added to the layer's error type.
+ *
  * @category sequencing
  * @since 2.0.0
  */
@@ -2268,6 +2558,12 @@ export declare const tapError: {
     /**
      * Performs the specified effect if this layer fails.
      *
+     * **Details**
+     *
+     * The callback receives the typed error. If the callback succeeds, the layer
+     * still fails with the original error; if the callback fails, that failure is
+     * added to the layer's error type.
+     *
      * @category sequencing
      * @since 2.0.0
      */
@@ -2275,6 +2571,12 @@ export declare const tapError: {
     /**
      * Performs the specified effect if this layer fails.
      *
+     * **Details**
+     *
+     * The callback receives the typed error. If the callback succeeds, the layer
+     * still fails with the original error; if the callback fails, that failure is
+     * added to the layer's error type.
+     *
      * @category sequencing
      * @since 2.0.0
      */
@@ -2284,6 +2586,7 @@ export declare const tapError: {
  * Performs the specified effect when this layer fails with any cause.
  *
  * **Details**
+ *
  * The callback receives the layer's `Cause`, so it can inspect typed errors,
  * defects, and interruption information. If the callback succeeds, the layer
  * fails again with the original cause; if the callback fails, that failure is
@@ -2297,6 +2600,7 @@ export declare const tapCause: {
      * Performs the specified effect when this layer fails with any cause.
      *
      * **Details**
+     *
      * The callback receives the layer's `Cause`, so it can inspect typed errors,
      * defects, and interruption information. If the callback succeeds, the layer
      * fails again with the original cause; if the callback fails, that failure is
@@ -2310,6 +2614,7 @@ export declare const tapCause: {
      * Performs the specified effect when this layer fails with any cause.
      *
      * **Details**
+     *
      * The callback receives the layer's `Cause`, so it can inspect typed errors,
      * defects, and interruption information. If the callback succeeds, the layer
      * fails again with the original cause; if the callback fails, that failure is
@@ -2321,8 +2626,13 @@ export declare const tapCause: {
     <RIn, E, XE extends E, ROut, RIn2, E2, X>(self: Layer<ROut, E, RIn>, f: (cause: Cause.Cause<XE>) => Effect<X, E2, RIn2>): Layer<ROut, E | E2, RIn | Exclude<RIn2, Scope.Scope>>;
 };
 /**
- * Translates effect failure into death of the fiber, making all failures
- * unchecked and not a part of the type of the layer.
+ * Converts layer construction failures into defects, removing them from the
+ * layer's error type.
+ *
+ * **Details**
+ *
+ * Use this only when failures should be treated as unrecoverable defects rather
+ * than typed errors that callers can handle.
  *
  * **Example** (Converting layer failures to defects)
  *
@@ -2338,7 +2648,7 @@ export declare const tapCause: {
  * }>()("Database") {}
  *
  * // Layer that can fail during construction
- * const flakyDatabaseLayer = Layer.effect(Database)(Effect.gen(function*() {
+ * const flakyDatabaseLayer = Layer.effect(Database, Effect.gen(function*() {
  *   console.log("connecting")
  *   return yield* new DatabaseError({ message: "Connection failed" })
  * }))
@@ -2368,7 +2678,16 @@ declare const catch_: {
 };
 export { 
 /**
- * Recovers from all errors.
+ * Recovers from all typed errors by switching to another layer.
+ *
+ * **When to use**
+ *
+ * Use `catch` when every typed construction error should use the same recovery
+ * path. Use `catchTag` to recover from specific tagged errors, and `catchCause`
+ * when recovery needs the full failure cause.
+ *
+ * @see {@link catchTag} for recovering from specific tagged errors
+ * @see {@link catchCause} for recovering with access to the full cause
  *
  * @category error handling
  * @since 4.0.0
@@ -2377,6 +2696,12 @@ catch_ as catch };
 /**
  * Recovers from specific tagged errors.
  *
+ * **When to use**
+ *
+ * Use `catchTag` when only some tagged construction errors should be recovered.
+ * Use `catchCause` when recovery depends on defects, interruption, or other
+ * cause information.
+ *
  * **Example** (Recovering from tagged layer errors)
  *
  * ```ts
@@ -2388,15 +2713,17 @@ catch_ as catch };
  *   readonly apiUrl: string
  * }>()("Config") {}
  *
- * const configLayer = Layer.effect(Config)(Effect.fail(new ConfigError()))
+ * const configLayer = Layer.effect(Config, Effect.fail(new ConfigError()))
  *
- * const fallbackLayer = Layer.succeed(Config)({ apiUrl: "http://localhost" })
+ * const fallbackLayer = Layer.succeed(Config, { apiUrl: "http://localhost" })
  *
  * const recovered = configLayer.pipe(
  *   Layer.catchTag("ConfigError", () => fallbackLayer)
  * )
  * ```
  *
+ * @see {@link catchCause} for recovering with access to the full cause
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2404,6 +2731,12 @@ export declare const catchTag: {
     /**
      * Recovers from specific tagged errors.
      *
+     * **When to use**
+     *
+     * Use `catchTag` when only some tagged construction errors should be recovered.
+     * Use `catchCause` when recovery depends on defects, interruption, or other
+     * cause information.
+     *
      * **Example** (Recovering from tagged layer errors)
      *
      * ```ts
@@ -2415,15 +2748,17 @@ export declare const catchTag: {
      *   readonly apiUrl: string
      * }>()("Config") {}
      *
-     * const configLayer = Layer.effect(Config)(Effect.fail(new ConfigError()))
+     * const configLayer = Layer.effect(Config, Effect.fail(new ConfigError()))
      *
-     * const fallbackLayer = Layer.succeed(Config)({ apiUrl: "http://localhost" })
+     * const fallbackLayer = Layer.succeed(Config, { apiUrl: "http://localhost" })
      *
      * const recovered = configLayer.pipe(
      *   Layer.catchTag("ConfigError", () => fallbackLayer)
      * )
      * ```
      *
+     * @see {@link catchCause} for recovering with access to the full cause
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -2431,6 +2766,12 @@ export declare const catchTag: {
     /**
      * Recovers from specific tagged errors.
      *
+     * **When to use**
+     *
+     * Use `catchTag` when only some tagged construction errors should be recovered.
+     * Use `catchCause` when recovery depends on defects, interruption, or other
+     * cause information.
+     *
      * **Example** (Recovering from tagged layer errors)
      *
      * ```ts
@@ -2442,15 +2783,17 @@ export declare const catchTag: {
      *   readonly apiUrl: string
      * }>()("Config") {}
      *
-     * const configLayer = Layer.effect(Config)(Effect.fail(new ConfigError()))
+     * const configLayer = Layer.effect(Config, Effect.fail(new ConfigError()))
      *
-     * const fallbackLayer = Layer.succeed(Config)({ apiUrl: "http://localhost" })
+     * const fallbackLayer = Layer.succeed(Config, { apiUrl: "http://localhost" })
      *
      * const recovered = configLayer.pipe(
      *   Layer.catchTag("ConfigError", () => fallbackLayer)
      * )
      * ```
      *
+     * @see {@link catchCause} for recovering with access to the full cause
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -2459,10 +2802,18 @@ export declare const catchTag: {
 /**
  * Recovers from any failure cause by switching to another layer.
  *
+ * **When to use**
+ *
+ * Use `catchCause` when recovery needs more than the typed error, such as
+ * defects or interruption information. Use `catchTag` when recovery only needs
+ * to match specific tagged errors.
+ *
  * **Details**
+ *
  * The handler receives the full `Cause` of the failed layer, including typed
- * errors, defects, and interruption information, and returns the fallback layer
- * to build instead.
+ * errors, unexpected defects, and interruption information, and returns the
+ * fallback layer to build instead. Finalizers for resources acquired by the
+ * failed layer are still run before the fallback layer is acquired.
  *
  * **Example** (Recovering from layer failures by cause)
  *
@@ -2477,13 +2828,13 @@ export declare const catchTag: {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
- * const primaryDatabaseLayer = Layer.effect(Database)(
+ * const primaryDatabaseLayer = Layer.effect(Database,
  *   Effect.fail(new DatabaseError({ message: "Primary DB unreachable" }))
  * )
  *
  * const databaseWithFallback = primaryDatabaseLayer.pipe(
  *   Layer.catchCause(() => {
- *     return Layer.succeed(Database)({
+ *     return Layer.succeed(Database, {
  *       query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
  *     })
  *   })
@@ -2501,6 +2852,8 @@ export declare const catchTag: {
  * // Memory: SELECT * FROM users
  * ```
  *
+ * @see {@link catchTag} for recovering from specific tagged errors
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2508,10 +2861,18 @@ export declare const catchCause: {
     /**
      * Recovers from any failure cause by switching to another layer.
      *
+     * **When to use**
+     *
+     * Use `catchCause` when recovery needs more than the typed error, such as
+     * defects or interruption information. Use `catchTag` when recovery only needs
+     * to match specific tagged errors.
+     *
      * **Details**
+     *
      * The handler receives the full `Cause` of the failed layer, including typed
-     * errors, defects, and interruption information, and returns the fallback layer
-     * to build instead.
+     * errors, unexpected defects, and interruption information, and returns the
+     * fallback layer to build instead. Finalizers for resources acquired by the
+     * failed layer are still run before the fallback layer is acquired.
      *
      * **Example** (Recovering from layer failures by cause)
      *
@@ -2526,13 +2887,13 @@ export declare const catchCause: {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * const primaryDatabaseLayer = Layer.effect(Database)(
+     * const primaryDatabaseLayer = Layer.effect(Database,
      *   Effect.fail(new DatabaseError({ message: "Primary DB unreachable" }))
      * )
      *
      * const databaseWithFallback = primaryDatabaseLayer.pipe(
      *   Layer.catchCause(() => {
-     *     return Layer.succeed(Database)({
+     *     return Layer.succeed(Database, {
      *       query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
      *     })
      *   })
@@ -2550,6 +2911,8 @@ export declare const catchCause: {
      * // Memory: SELECT * FROM users
      * ```
      *
+     * @see {@link catchTag} for recovering from specific tagged errors
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -2557,10 +2920,18 @@ export declare const catchCause: {
     /**
      * Recovers from any failure cause by switching to another layer.
      *
+     * **When to use**
+     *
+     * Use `catchCause` when recovery needs more than the typed error, such as
+     * defects or interruption information. Use `catchTag` when recovery only needs
+     * to match specific tagged errors.
+     *
      * **Details**
+     *
      * The handler receives the full `Cause` of the failed layer, including typed
-     * errors, defects, and interruption information, and returns the fallback layer
-     * to build instead.
+     * errors, unexpected defects, and interruption information, and returns the
+     * fallback layer to build instead. Finalizers for resources acquired by the
+     * failed layer are still run before the fallback layer is acquired.
      *
      * **Example** (Recovering from layer failures by cause)
      *
@@ -2575,13 +2946,13 @@ export declare const catchCause: {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * const primaryDatabaseLayer = Layer.effect(Database)(
+     * const primaryDatabaseLayer = Layer.effect(Database,
      *   Effect.fail(new DatabaseError({ message: "Primary DB unreachable" }))
      * )
      *
      * const databaseWithFallback = primaryDatabaseLayer.pipe(
      *   Layer.catchCause(() => {
-     *     return Layer.succeed(Database)({
+     *     return Layer.succeed(Database, {
      *       query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
      *     })
      *   })
@@ -2599,6 +2970,8 @@ export declare const catchCause: {
      * // Memory: SELECT * FROM users
      * ```
      *
+     * @see {@link catchTag} for recovering from specific tagged errors
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -2607,6 +2980,11 @@ export declare const catchCause: {
 /**
  * Updates a service in the context with a new implementation.
  *
+ * **When to use**
+ *
+ * Use this to adapt or extend a service's behavior during the creation of a
+ * layer.
+ *
  * **Details**
  *
  * This function modifies the existing implementation of a service in the
@@ -2614,11 +2992,6 @@ export declare const catchCause: {
  * transformation function `f`, and replaces the old service with the
  * transformed one.
  *
- * **When to Use**
- *
- * This is useful for adapting or extending a service's behavior during the
- * creation of a layer.
- *
  * @category utils
  * @since 3.13.0
  */
@@ -2626,6 +2999,11 @@ export declare const updateService: {
     /**
      * Updates a service in the context with a new implementation.
      *
+     * **When to use**
+     *
+     * Use this to adapt or extend a service's behavior during the creation of a
+     * layer.
+     *
      * **Details**
      *
      * This function modifies the existing implementation of a service in the
@@ -2633,11 +3011,6 @@ export declare const updateService: {
      * transformation function `f`, and replaces the old service with the
      * transformed one.
      *
-     * **When to Use**
-     *
-     * This is useful for adapting or extending a service's behavior during the
-     * creation of a layer.
-     *
      * @category utils
      * @since 3.13.0
      */
@@ -2645,6 +3018,11 @@ export declare const updateService: {
     /**
      * Updates a service in the context with a new implementation.
      *
+     * **When to use**
+     *
+     * Use this to adapt or extend a service's behavior during the creation of a
+     * layer.
+     *
      * **Details**
      *
      * This function modifies the existing implementation of a service in the
@@ -2652,11 +3030,6 @@ export declare const updateService: {
      * transformation function `f`, and replaces the old service with the
      * transformed one.
      *
-     * **When to Use**
-     *
-     * This is useful for adapting or extending a service's behavior during the
-     * creation of a layer.
-     *
      * @category utils
      * @since 3.13.0
      */
@@ -2665,6 +3038,13 @@ export declare const updateService: {
 /**
  * Creates a fresh version of this layer that will not be shared.
  *
+ * **When to use**
+ *
+ * Use `fresh` when two parts of an application must receive separate instances
+ * of a resource, such as two independent client sessions. Do not use it just to
+ * work around confusing composition: by default, sharing the same layer value is
+ * usually the desired behavior.
+ *
  * **Example** (Creating non-shared layer instances)
  *
  * ```ts
@@ -2682,12 +3062,12 @@ export declare const updateService: {
  *   readonly counterId: number
  * }>()("Right") {}
  *
- * const leftLayer = Layer.effect(Left)(Effect.gen(function*() {
+ * const leftLayer = Layer.effect(Left, Effect.gen(function*() {
  *   const counter = yield* Counter
  *   return { counterId: counter.id }
  * }))
  *
- * const rightLayer = Layer.effect(Right)(Effect.gen(function*() {
+ * const rightLayer = Layer.effect(Right, Effect.gen(function*() {
  *   const counter = yield* Counter
  *   return { counterId: counter.id }
  * }))
@@ -2701,7 +3081,7 @@ export declare const updateService: {
  * const program = Effect.gen(function*() {
  *   const nextId = yield* Ref.make(0)
  *
- *   const counterLayer = Layer.effect(Counter)(Effect.gen(function*() {
+ *   const counterLayer = Layer.effect(Counter, Effect.gen(function*() {
  *     const id = yield* Ref.updateAndGet(nextId, (n) => n + 1)
  *     console.log("constructed Counter")
  *     return { id }
@@ -2736,8 +3116,16 @@ export declare const updateService: {
  */
 export declare const fresh: <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, R>;
 /**
- * Builds this layer and uses it until it is interrupted. This is useful when
- * your entire application is a layer, such as an HTTP server.
+ * Builds this layer and keeps it alive until the returned effect is interrupted.
+ *
+ * **When to use**
+ *
+ * Use this when your entire application is a layer, such as an HTTP server.
+ *
+ * **Details**
+ *
+ * When the returned effect is interrupted, the layer scope is closed and all
+ * finalizers registered during layer acquisition are run.
  *
  * **Example** (Launching an application layer)
  *
@@ -2754,7 +3142,7 @@ export declare const fresh: <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, R>;
  * }>()("Logger") {}
  *
  * // Server layer that starts an HTTP server
- * const serverLayer = Layer.effect(HttpServer)(Effect.gen(function*() {
+ * const serverLayer = Layer.effect(HttpServer, Effect.gen(function*() {
  *   yield* Console.log("Starting HTTP server...")
  *
  *   return {
@@ -2769,7 +3157,7 @@ export declare const fresh: <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, R>;
  *   }
  * }))
  *
- * const loggerLayer = Layer.succeed(Logger)({
+ * const loggerLayer = Layer.succeed(Logger, {
  *   log: Effect.fn("Logger.log")((msg: string) => Console.log(`[LOG] ${msg}`))
  * })
  *
@@ -2794,11 +3182,13 @@ export declare const launch: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect
 /**
  * A utility type for creating partial mocks of services in testing.
  *
+ * **Details**
+ *
  * This type makes Effect methods and Effect-returning functions optional,
  * while keeping non-Effect properties required. This allows you to provide
  * only the methods you need to test while leaving others unimplemented.
  *
- * @category Testing
+ * @category testing
  * @since 3.17.0
  */
 export type PartialEffectful<A extends object> = Types.Simplify<{
@@ -2809,8 +3199,16 @@ export type PartialEffectful<A extends object> = Types.Simplify<{
 type AnyEffectOrStream = Effect<any, any, any> | Stream.Stream<any, any, any> | Channel.Channel<any, any, any, any, any, any, any> | ((...args: any) => Effect<any, any, any>) | ((...args: any) => Stream.Stream<any, any, any>) | ((...args: any) => Channel.Channel<any, any, any, any, any, any, any>);
 /**
  * Creates a mock layer for testing purposes. You can provide a partial
- * implementation of the service, and any methods not provided will
- * throw an unimplemented defect when called.
+ * implementation of the service. Any missing members that are `Effect`s,
+ * `Stream`s, `Channel`s, or functions returning them will fail with an
+ * unimplemented defect when used.
+ *
+ * **Details**
+ *
+ * Missing members are represented by a value that can be used as an `Effect`,
+ * `Stream`, `Channel`, or as a function returning an `Effect`. This lets the
+ * mock preserve the shape of common service methods while still failing loudly
+ * when an unimplemented member is exercised.
  *
  * **Example** (Mocking services for tests)
  *
@@ -2851,14 +3249,22 @@ type AnyEffectOrStream = Effect<any, any, any> | Stream.Stream<any, any, any> |
  * )
  * ```
  *
- * @category Testing
+ * @category testing
  * @since 3.17.0
  */
 export declare const mock: {
     /**
      * Creates a mock layer for testing purposes. You can provide a partial
-     * implementation of the service, and any methods not provided will
-     * throw an unimplemented defect when called.
+     * implementation of the service. Any missing members that are `Effect`s,
+     * `Stream`s, `Channel`s, or functions returning them will fail with an
+     * unimplemented defect when used.
+     *
+     * **Details**
+     *
+     * Missing members are represented by a value that can be used as an `Effect`,
+     * `Stream`, `Channel`, or as a function returning an `Effect`. This lets the
+     * mock preserve the shape of common service methods while still failing loudly
+     * when an unimplemented member is exercised.
      *
      * **Example** (Mocking services for tests)
      *
@@ -2899,14 +3305,22 @@ export declare const mock: {
      * )
      * ```
      *
-     * @category Testing
+     * @category testing
      * @since 3.17.0
      */
     <I, S extends object>(service: Context.Key<I, S>): (implementation: PartialEffectful<S>) => Layer<I>;
     /**
      * Creates a mock layer for testing purposes. You can provide a partial
-     * implementation of the service, and any methods not provided will
-     * throw an unimplemented defect when called.
+     * implementation of the service. Any missing members that are `Effect`s,
+     * `Stream`s, `Channel`s, or functions returning them will fail with an
+     * unimplemented defect when used.
+     *
+     * **Details**
+     *
+     * Missing members are represented by a value that can be used as an `Effect`,
+     * `Stream`, `Channel`, or as a function returning an `Effect`. This lets the
+     * mock preserve the shape of common service methods while still failing loudly
+     * when an unimplemented member is exercised.
      *
      * **Example** (Mocking services for tests)
      *
@@ -2947,16 +3361,18 @@ export declare const mock: {
      * )
      * ```
      *
-     * @category Testing
+     * @category testing
      * @since 3.17.0
      */
     <I, S extends object>(service: Context.Key<I, S>, implementation: Types.NoInfer<PartialEffectful<S>>): Layer<I>;
 };
 /**
- * Ensures that an layer's success type extends a given type `ROut`.
+ * Ensures that a layer's success type extends a given type `ROut`.
+ *
+ * **Details**
  *
  * This function provides compile-time type checking to ensure that the success
- * value of an layer conforms to a specific type constraint.
+ * value of a layer conforms to a specific type constraint.
  *
  * **Example** (Constraining layer success types)
  *
@@ -2978,15 +3394,17 @@ export declare const mock: {
  * // Type 'string' is not assignable to type 'number'
  * ```
  *
- * @category Type constraints
+ * @category utility types
  * @since 4.0.0
  */
 export declare const satisfiesSuccessType: <ROut>() => <ROut2 extends ROut, E, RIn>(layer: Layer<ROut2, E, RIn>) => Layer<ROut2, E, RIn>;
 /**
- * Ensures that an layer's error type extends a given type `E`.
+ * Ensures that a layer's error type extends a given type `E`.
+ *
+ * **Details**
  *
  * This function provides compile-time type checking to ensure that the error
- * type of an layer conforms to a specific type constraint.
+ * type of a layer conforms to a specific type constraint.
  *
  * **Example** (Constraining layer error types)
  *
@@ -3009,15 +3427,17 @@ export declare const satisfiesSuccessType: <ROut>() => <ROut2 extends ROut, E, R
  * // Type 'string' is not assignable to type 'Error'
  * ```
  *
- * @category Type constraints
+ * @category utility types
  * @since 4.0.0
  */
 export declare const satisfiesErrorType: <E>() => <ROut, E2 extends E, RIn>(layer: Layer<ROut, E2, RIn>) => Layer<ROut, E2, RIn>;
 /**
- * Ensures that an layer's requirements type extends a given type `R`.
+ * Ensures that a layer's requirements type extends a given type `R`.
+ *
+ * **Details**
  *
  * This function provides compile-time type checking to ensure that the
- * requirements (context) type of an layer conforms to a specific type constraint.
+ * requirements type of a layer conforms to a specific type constraint.
  *
  * **Example** (Constraining layer service requirements)
  *
@@ -3039,7 +3459,7 @@ export declare const satisfiesErrorType: <E>() => <ROut, E2 extends E, RIn>(laye
  * // Type 'string' is not assignable to type 'number'
  * ```
  *
- * @category Type constraints
+ * @category utility types
  * @since 4.0.0
  */
 export declare const satisfiesServicesType: <RIn>() => <ROut, E, RIn2 extends RIn>(layer: Layer<ROut, E, RIn2>) => Layer<ROut, E, RIn2>;
@@ -3052,8 +3472,8 @@ export declare const satisfiesServicesType: <RIn>() => <ROut, E, RIn2 extends RI
  */
 export interface SpanOptions extends Tracer.SpanOptions {
     /**
-     * A function that will be called when the span associated with the layer is
-     * ending (i.e. when the `Scope` that the span is associated with is closed).
+     * Runs when the span associated with the layer ends, which happens when the
+     * layer scope is closed.
      */
     readonly onEnd?: ((span: Tracer.Span, exit: Exit.Exit<unknown, unknown>) => Effect<void>) | undefined;
 }
@@ -3061,9 +3481,13 @@ export interface SpanOptions extends Tracer.SpanOptions {
  * Constructs a new `Layer` which creates a span and registers it as the current
  * parent span.
  *
+ * **Details**
+ *
  * This allows you to create a traced scope for layer construction, making all
  * operations within the layer constructor part of the same trace span. The span
- * is automatically closed when the layer's scope is closed.
+ * is automatically ended when the layer's scope is closed. If `onEnd` is
+ * provided, it receives the span and the layer scope's exit value when the span
+ * ends.
  *
  * **Example** (Tracing layer construction with a span)
  *
@@ -3109,6 +3533,7 @@ export declare const span: (name: string, options?: SpanOptions) => Layer<Tracer
  * Constructs a layer that provides an existing span as the current parent span.
  *
  * **Details**
+ *
  * The supplied span is made available through `Tracer.ParentSpan` for layers
  * that are built with this layer. This API does not create, end, or close the
  * span; the caller remains responsible for the span's lifetime.
@@ -3146,9 +3571,11 @@ export declare const span: (name: string, options?: SpanOptions) => Layer<Tracer
  */
 export declare const parentSpan: (span: Tracer.AnySpan) => Layer<Tracer.ParentSpan>;
 /**
- * Wraps a Layer with a new tracing span, making all operations in the layer
+ * Wraps a `Layer` with a new tracing span, making all operations in the layer
  * constructor part of the named trace span.
  *
+ * **Details**
+ *
  * This creates a new span for the layer's construction and execution. The span
  * is automatically ended when the layer's scope is closed. This is useful for
  * tracking the lifecycle and performance of layer initialization.
@@ -3197,8 +3624,7 @@ export declare const parentSpan: (span: Tracer.AnySpan) => Layer<Tracer.ParentSp
  *
  *   yield* logger.log("Application ready")
  *   return yield* database.query("SELECT * FROM users")
- * }).pipe(Effect.provide(appLayer)
- * )
+ * }).pipe(Effect.provide(appLayer))
  * ```
  *
  * @category tracing
@@ -3206,9 +3632,11 @@ export declare const parentSpan: (span: Tracer.AnySpan) => Layer<Tracer.ParentSp
  */
 export declare const withSpan: {
     /**
-     * Wraps a Layer with a new tracing span, making all operations in the layer
+     * Wraps a `Layer` with a new tracing span, making all operations in the layer
      * constructor part of the named trace span.
      *
+     * **Details**
+     *
      * This creates a new span for the layer's construction and execution. The span
      * is automatically ended when the layer's scope is closed. This is useful for
      * tracking the lifecycle and performance of layer initialization.
@@ -3257,8 +3685,7 @@ export declare const withSpan: {
      *
      *   yield* logger.log("Application ready")
      *   return yield* database.query("SELECT * FROM users")
-     * }).pipe(Effect.provide(appLayer)
-     * )
+     * }).pipe(Effect.provide(appLayer))
      * ```
      *
      * @category tracing
@@ -3266,9 +3693,11 @@ export declare const withSpan: {
      */
     (name: string, options?: SpanOptions): <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, Exclude<R, Tracer.ParentSpan>>;
     /**
-     * Wraps a Layer with a new tracing span, making all operations in the layer
+     * Wraps a `Layer` with a new tracing span, making all operations in the layer
      * constructor part of the named trace span.
      *
+     * **Details**
+     *
      * This creates a new span for the layer's construction and execution. The span
      * is automatically ended when the layer's scope is closed. This is useful for
      * tracking the lifecycle and performance of layer initialization.
@@ -3317,8 +3746,7 @@ export declare const withSpan: {
      *
      *   yield* logger.log("Application ready")
      *   return yield* database.query("SELECT * FROM users")
-     * }).pipe(Effect.provide(appLayer)
-     * )
+     * }).pipe(Effect.provide(appLayer))
      * ```
      *
      * @category tracing
@@ -3331,9 +3759,15 @@ export declare const withSpan: {
  * as their parent.
  *
  * **Details**
+ *
  * Use this to attach layer construction to an existing trace hierarchy. This API
  * does not create or end the supplied parent span.
  *
+ * When the supplied span is a native `Span`, layer construction also receives
+ * diagnostic information that helps associate failures with the layer call site.
+ * External spans are only installed as the parent span and do not add this
+ * diagnostic call-site information.
+ *
  * **Example** (Attaching layers to an existing parent span)
  *
  * ```ts
@@ -3393,9 +3827,15 @@ export declare const withParentSpan: {
      * as their parent.
      *
      * **Details**
+     *
      * Use this to attach layer construction to an existing trace hierarchy. This API
      * does not create or end the supplied parent span.
      *
+     * When the supplied span is a native `Span`, layer construction also receives
+     * diagnostic information that helps associate failures with the layer call site.
+     * External spans are only installed as the parent span and do not add this
+     * diagnostic call-site information.
+     *
      * **Example** (Attaching layers to an existing parent span)
      *
      * ```ts
@@ -3455,9 +3895,15 @@ export declare const withParentSpan: {
      * as their parent.
      *
      * **Details**
+     *
      * Use this to attach layer construction to an existing trace hierarchy. This API
      * does not create or end the supplied parent span.
      *
+     * When the supplied span is a native `Span`, layer construction also receives
+     * diagnostic information that helps associate failures with the layer call site.
+     * External spans are only installed as the parent span and do not add this
+     * diagnostic call-site information.
+     *
      * **Example** (Attaching layers to an existing parent span)
      *
      * ```ts