effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/Layer.d.ts

@@ -39,8 +39,8 @@ declare const TypeId = "~effect/Layer";
  * - E: The possible errors during layer construction
  * - RIn: The services this layer requires as dependencies
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Layer<in ROut, out E = never, out RIn = never> extends Variance<ROut, E, RIn>, Pipeable {
     [Unify.typeSymbol]?: unknown;
@@ -48,8 +48,14 @@ export interface Layer<in ROut, out E = never, out RIn = never> extends Variance
     [Unify.ignoreSymbol]?: LayerUnifyIgnore;
 }
 /**
- * @since 4.0.0
+ * Type-level hook that allows `Layer` values to participate in `Unify`
+ * inference.
+ *
+ * This is used by Effect's pipe and unification machinery to preserve the
+ * provided services, error, and requirements of a `Layer`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface LayerUnify<A extends {
     [Unify.typeSymbol]?: any;
@@ -57,16 +63,19 @@ export interface LayerUnify<A extends {
     Layer?: () => A[Unify.typeSymbol] extends Layer<any, any, any> | infer _ ? Layer<Success<Extract<A[Unify.typeSymbol], Any>>, Error<Extract<A[Unify.typeSymbol], Any>>, Services<Extract<A[Unify.typeSymbol], Any>>> : never;
 }
 /**
- * @since 4.0.0
+ * Type-level marker used by `Unify` for `Layer` types that should be ignored
+ * during unification.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface LayerUnifyIgnore {
 }
 /**
  * The variance interface for Layer type parameters.
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Variance<in ROut, out E, out RIn> {
     readonly [TypeId]: {
@@ -81,8 +90,8 @@ export interface Variance<in ROut, out E, out RIn> {
  * This interface is used to constrain generic types to Layer types
  * without specifying exact type parameters.
  *
- * @since 3.9.0
  * @category type-level
+ * @since 3.9.0
  */
 export interface Any {
     readonly [TypeId]: {
@@ -94,22 +103,22 @@ export interface Any {
 /**
  * Extracts the service dependencies (RIn) from a Layer type.
  *
- * @since 2.0.0
  * @category type-level
+ * @since 2.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.
  *
- * @since 2.0.0
  * @category type-level
+ * @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.
  *
- * @since 2.0.0
  * @category type-level
+ * @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";
@@ -119,7 +128,8 @@ declare const MemoMapTypeId = "~effect/Layer/MemoMap";
  * The MemoMap prevents duplicate construction of the same layer instance,
  * enabling efficient resource sharing across layer dependencies.
  *
- * @example
+ * **Example** (Sharing layer construction with a memo map)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -141,17 +151,19 @@ declare const MemoMapTypeId = "~effect/Layer/MemoMap";
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface MemoMap {
     readonly [MemoMapTypeId]: typeof MemoMapTypeId;
+    readonly get: <RIn, E, ROut>(layer: Layer<ROut, E, RIn>, scope: Scope.Scope) => Effect<Context.Context<ROut>, E, RIn> | undefined;
     readonly getOrElseMemoize: <RIn, E, ROut>(layer: Layer<ROut, E, RIn>, scope: Scope.Scope, build: (memoMap: MemoMap, scope: Scope.Scope) => Effect<Context.Context<ROut>, E, RIn>) => Effect<Context.Context<ROut>, E, RIn>;
 }
 /**
  * Returns `true` if the specified value is a `Layer`, `false` otherwise.
  *
- * @example
+ * **Example** (Checking whether a value is a layer)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -168,8 +180,8 @@ export interface MemoMap {
  * console.log(Layer.isLayer(notALayer)) // false
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const isLayer: (u: unknown) => u is Layer<unknown, unknown, unknown>;
 /**
@@ -178,7 +190,8 @@ export declare const isLayer: (u: unknown) => u is Layer<unknown, unknown, unkno
  * 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.
  *
- * @example
+ * **Example** (Constructing a layer from a build function)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -195,8 +208,8 @@ export declare const isLayer: (u: unknown) => u is Layer<unknown, unknown, unkno
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromBuild: <ROut, E, RIn>(build: (memoMap: MemoMap, scope: Scope.Scope) => Effect<Context.Context<ROut>, E, RIn>) => Layer<ROut, E, RIn>;
 /**
@@ -206,7 +219,8 @@ export declare const fromBuild: <ROut, E, RIn>(build: (memoMap: MemoMap, scope:
  * This is similar to `fromBuild` but provides automatic memoization of the layer construction.
  * The layer will be memoized based on the provided `MemoMap`.
  *
- * @example
+ * **Example** (Memoizing layer construction)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -223,14 +237,15 @@ export declare const fromBuild: <ROut, E, RIn>(build: (memoMap: MemoMap, scope:
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromBuildMemo: <ROut, E, RIn>(build: (memoMap: MemoMap, scope: Scope.Scope) => Effect<Context.Context<ROut>, E, RIn>) => Layer<ROut, E, RIn>;
 /**
  * Constructs a `MemoMap` that can be used to build additional layers.
  *
- * @example
+ * **Example** (Creating a memo map unsafely)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -252,14 +267,23 @@ export declare const fromBuildMemo: <ROut, E, RIn>(build: (memoMap: MemoMap, sco
  * })
  * ```
  *
- * @since 4.0.0
  * @category memo map
+ * @since 4.0.0
  */
 export declare const makeMemoMapUnsafe: () => MemoMap;
+/**
+ * Constructs a child `MemoMap` that can reuse layers already memoized in the
+ * parent while isolating any new layer allocations to the child map.
+ *
+ * @since 4.0.0
+ * @category memo map
+ */
+export declare const forkMemoMapUnsafe: (parent: MemoMap) => MemoMap;
 /**
  * Constructs a `MemoMap` that can be used to build additional layers.
  *
- * @example
+ * **Example** (Creating a memo map in an effect)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -281,10 +305,18 @@ export declare const makeMemoMapUnsafe: () => MemoMap;
  * })
  * ```
  *
- * @since 2.0.0
  * @category memo map
+ * @since 2.0.0
  */
 export declare const makeMemoMap: Effect<MemoMap>;
+/**
+ * Constructs a child `MemoMap` that can reuse layers already memoized in the
+ * parent while isolating any new layer allocations to the child map.
+ *
+ * @since 4.0.0
+ * @category memo map
+ */
+export declare const forkMemoMap: (parent: MemoMap) => Effect<MemoMap>;
 declare const CurrentMemoMap_base: Context.ServiceClass<CurrentMemoMap, "effect/Layer/CurrentMemoMap", MemoMap>;
 /**
  * A service reference for the current `MemoMap` used in layer construction.
@@ -292,8 +324,8 @@ declare const CurrentMemoMap_base: Context.ServiceClass<CurrentMemoMap, "effect/
  * This service provides access to the current memoization map during layer building,
  * allowing layers to share memoized results.
  *
- * @since 3.13.0
  * @category models
+ * @since 3.13.0
  */
 export declare class CurrentMemoMap extends CurrentMemoMap_base {
     static getOrCreate: <Services>(self: Context.Context<Services>) => MemoMap;
@@ -302,7 +334,8 @@ export declare class CurrentMemoMap extends CurrentMemoMap_base {
  * Builds a layer into an `Effect` value, using the specified `MemoMap` to memoize
  * the layer construction.
  *
- * @example
+ * **Example** (Building layers with an explicit memo map)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -342,15 +375,16 @@ export declare class CurrentMemoMap extends CurrentMemoMap_base {
  * })
  * ```
  *
- * @since 2.0.0
  * @category memo map
+ * @since 2.0.0
  */
 export declare const buildWithMemoMap: {
     /**
      * Builds a layer into an `Effect` value, using the specified `MemoMap` to memoize
      * the layer construction.
      *
-     * @example
+     * **Example** (Building layers with an explicit memo map)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -390,15 +424,16 @@ export declare const buildWithMemoMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category memo map
+     * @since 2.0.0
      */
     (memoMap: MemoMap, scope: Scope.Scope): <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<Context.Context<ROut>, E, RIn>;
     /**
      * Builds a layer into an `Effect` value, using the specified `MemoMap` to memoize
      * the layer construction.
      *
-     * @example
+     * **Example** (Building layers with an explicit memo map)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -438,15 +473,16 @@ export declare const buildWithMemoMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category memo map
+     * @since 2.0.0
      */
     <RIn, E, ROut>(self: Layer<ROut, E, RIn>, memoMap: MemoMap, scope: Scope.Scope): Effect<Context.Context<ROut>, E, RIn>;
 };
 /**
  * Builds a layer into a scoped value.
  *
- * @example
+ * **Example** (Building a layer into a context)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -470,8 +506,8 @@ export declare const buildWithMemoMap: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category destructors
+ * @since 2.0.0
  */
 export declare const build: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<Context.Context<ROut>, E, RIn | Scope.Scope>;
 /**
@@ -481,7 +517,8 @@ export declare const build: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<
  * the services output by the layer exceed the lifetime of the effect the
  * layer is provided to.
  *
- * @example
+ * **Example** (Building a layer with an explicit scope)
+ *
  * ```ts
  * import { Effect, Layer, Scope, Context } from "effect"
  *
@@ -511,8 +548,8 @@ export declare const build: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<
  * })
  * ```
  *
- * @since 2.0.0
  * @category destructors
+ * @since 2.0.0
  */
 export declare const buildWithScope: {
     /**
@@ -522,7 +559,8 @@ export declare const buildWithScope: {
      * the services output by the layer exceed the lifetime of the effect the
      * layer is provided to.
      *
-     * @example
+     * **Example** (Building a layer with an explicit scope)
+     *
      * ```ts
      * import { Effect, Layer, Scope, Context } from "effect"
      *
@@ -552,8 +590,8 @@ export declare const buildWithScope: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category destructors
+     * @since 2.0.0
      */
     (scope: Scope.Scope): <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<Context.Context<ROut>, E, RIn>;
     /**
@@ -563,7 +601,8 @@ export declare const buildWithScope: {
      * the services output by the layer exceed the lifetime of the effect the
      * layer is provided to.
      *
-     * @example
+     * **Example** (Building a layer with an explicit scope)
+     *
      * ```ts
      * import { Effect, Layer, Scope, Context } from "effect"
      *
@@ -593,15 +632,16 @@ export declare const buildWithScope: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category destructors
+     * @since 2.0.0
      */
     <RIn, E, ROut>(self: Layer<ROut, E, RIn>, scope: Scope.Scope): Effect<Context.Context<ROut>, E, RIn>;
 };
 /**
  * Constructs a layer from the specified value.
  *
- * @example
+ * **Example** (Providing services from values)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -637,14 +677,15 @@ export declare const buildWithScope: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const succeed: {
     /**
      * Constructs a layer from the specified value.
      *
-     * @example
+     * **Example** (Providing services from values)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -680,14 +721,15 @@ export declare const succeed: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category constructors
+     * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>): (resource: S) => Layer<I>;
     /**
      * Constructs a layer from the specified value.
      *
-     * @example
+     * **Example** (Providing services from values)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -723,8 +765,8 @@ export declare const succeed: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category constructors
+     * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>, resource: Types.NoInfer<S>): Layer<I>;
 };
@@ -735,7 +777,8 @@ export declare const succeed: {
  * This is a more general version of `succeed` that allows you to provide multiple
  * services at once through a `Context`.
  *
- * @example
+ * **Example** (Providing multiple services from a context)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -758,8 +801,8 @@ export declare const succeed: {
  * const layer = Layer.succeedContext(context)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const succeedContext: <A>(context: Context.Context<A>) => Layer<A>;
 /**
@@ -768,15 +811,16 @@ export declare const succeedContext: <A>(context: Context.Context<A>) => Layer<A
  * This layer provides no services and can be used as a neutral element
  * in layer composition or as a starting point for building layers.
  *
- * @example
+ * **Example** (Creating an empty layer)
+ *
  * ```ts
  * import { Layer } from "effect"
  *
  * const emptyLayer = Layer.empty
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const empty: Layer<never>;
 /**
@@ -785,7 +829,8 @@ export declare const empty: Layer<never>;
  * This is a lazy version of `succeed` where the service value is computed
  * synchronously only when the layer is built.
  *
- * @example
+ * **Example** (Lazily providing a service)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -798,8 +843,8 @@ export declare const empty: Layer<never>;
  * }))
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const sync: {
     /**
@@ -808,7 +853,8 @@ export declare const sync: {
      * This is a lazy version of `succeed` where the service value is computed
      * synchronously only when the layer is built.
      *
-     * @example
+     * **Example** (Lazily providing a service)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -821,8 +867,8 @@ export declare const sync: {
      * }))
      * ```
      *
-     * @since 2.0.0
      * @category constructors
+     * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>): (evaluate: LazyArg<S>) => Layer<I>;
     /**
@@ -831,7 +877,8 @@ export declare const sync: {
      * This is a lazy version of `succeed` where the service value is computed
      * synchronously only when the layer is built.
      *
-     * @example
+     * **Example** (Lazily providing a service)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -844,8 +891,8 @@ export declare const sync: {
      * }))
      * ```
      *
-     * @since 2.0.0
      * @category constructors
+     * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>, evaluate: LazyArg<Types.NoInfer<S>>): Layer<I>;
 };
@@ -856,7 +903,8 @@ export declare const sync: {
  * This is a lazy version of `succeedContext` where the Context is computed
  * synchronously only when the layer is built.
  *
- * @example
+ * **Example** (Lazily providing a context)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -871,8 +919,8 @@ export declare const sync: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const syncContext: <A>(evaluate: LazyArg<Context.Context<A>>) => Layer<A>;
 /**
@@ -888,7 +936,8 @@ export declare const syncContext: <A>(evaluate: LazyArg<Context.Context<A>>) =>
  *
  * - `Layer.scoped`
  *
- * @example
+ * **Example** (Creating a layer from an effect)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -903,8 +952,8 @@ export declare const syncContext: <A>(evaluate: LazyArg<Context.Context<A>>) =>
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const effect: {
     /**
@@ -920,7 +969,8 @@ export declare const effect: {
      *
      * - `Layer.scoped`
      *
-     * @example
+     * **Example** (Creating a layer from an effect)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -935,8 +985,8 @@ export declare const effect: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @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>>;
     /**
@@ -952,7 +1002,8 @@ export declare const effect: {
      *
      * - `Layer.scoped`
      *
-     * @example
+     * **Example** (Creating a layer from an effect)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -967,8 +1018,8 @@ export declare const effect: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @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>>;
 };
@@ -979,7 +1030,8 @@ export declare const effect: {
  * 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
+ * **Example** (Creating a layer from an effectful context)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -995,8 +1047,8 @@ export declare const effect: {
  * )
  * ```
  *
- * @since 2.0.0
  * @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>>;
 /**
@@ -1011,7 +1063,8 @@ export declare const effectContext: <A, E, R>(effect: Effect<Context.Context<A>,
  *
  * - `Layer.scopedDiscard`
  *
- * @example
+ * **Example** (Running an effect during layer construction)
+ *
  * ```ts
  * import { Effect, Layer } from "effect"
  *
@@ -1022,8 +1075,8 @@ export declare const effectContext: <A, E, R>(effect: Effect<Context.Context<A>,
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const effectDiscard: <X, E, R>(effect: Effect<X, E, R>) => Layer<never, E, Exclude<R, Scope.Scope>>;
 /**
@@ -1032,7 +1085,8 @@ export declare const effectDiscard: <X, E, R>(effect: Effect<X, E, R>) => Layer<
  * The factory is evaluated only when the suspended layer is first built, and
  * the result is memoized with normal layer sharing semantics.
  *
- * @example
+ * **Example** (Choosing a layer lazily)
+ *
  * ```ts
  * import { Layer, Context } from "effect"
  *
@@ -1047,8 +1101,8 @@ export declare const effectDiscard: <X, E, R>(effect: Effect<X, E, R>) => Layer<
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const suspend: <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>) => Layer<A, E, R>;
 /**
@@ -1058,7 +1112,8 @@ export declare const suspend: <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>) => La
  * use that Layer directly. The resulting Layer will have the combined error and
  * dependency types from both the outer Effect and the inner Layer.
  *
- * @example
+ * **Example** (Unwrapping an effectful layer)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -1073,8 +1128,8 @@ export declare const suspend: <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>) => La
  * const unwrappedLayer = Layer.unwrap(layerEffect)
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 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>>;
 /**
@@ -1083,7 +1138,8 @@ export declare const unwrap: <A, E1, R1, E, R>(self: Effect<Layer<A, E1, R1>, E,
  * 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.
  *
- * @example
+ * **Example** (Merging independent layers)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -1105,8 +1161,8 @@ export declare const unwrap: <A, E1, R1, E, R>(self: Effect<Layer<A, E1, R1>, E,
  * const mergedLayer = Layer.mergeAll(dbLayer, loggerLayer)
  * ```
  *
- * @since 2.0.0
  * @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]>>;
 /**
@@ -1115,7 +1171,8 @@ export declare const mergeAll: <Layers extends [Layer<never, any, any>, ...Array
  * 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
+ * **Example** (Merging two layers)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -1137,8 +1194,8 @@ export declare const mergeAll: <Layers extends [Layer<never, any, any>, ...Array
  * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
  * ```
  *
- * @since 2.0.0
  * @category zipping
+ * @since 2.0.0
  */
 export declare const merge: {
     /**
@@ -1147,7 +1204,8 @@ export declare const merge: {
      * 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
+     * **Example** (Merging two layers)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1169,8 +1227,8 @@ export declare const merge: {
      * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
      * ```
      *
-     * @since 2.0.0
      * @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>;
     /**
@@ -1179,7 +1237,8 @@ export declare const merge: {
      * 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
+     * **Example** (Merging two layers)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1201,8 +1260,8 @@ export declare const merge: {
      * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
      * ```
      *
-     * @since 2.0.0
      * @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>;
     /**
@@ -1211,7 +1270,8 @@ export declare const merge: {
      * 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
+     * **Example** (Merging two layers)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1233,8 +1293,8 @@ export declare const merge: {
      * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
      * ```
      *
-     * @since 2.0.0
      * @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>;
     /**
@@ -1243,7 +1303,8 @@ export declare const merge: {
      * 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
+     * **Example** (Merging two layers)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1265,8 +1326,8 @@ export declare const merge: {
      * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
      * ```
      *
-     * @since 2.0.0
      * @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>;
 };
@@ -1275,7 +1336,8 @@ export declare const merge: {
  * 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.
  *
- * @example
+ * **Example** (Providing layer dependencies)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -1333,8 +1395,8 @@ export declare const merge: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const provide: {
     /**
@@ -1342,7 +1404,8 @@ export declare const provide: {
      * 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.
      *
-     * @example
+     * **Example** (Providing layer dependencies)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1400,8 +1463,8 @@ export declare const provide: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @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>>;
     /**
@@ -1409,7 +1472,8 @@ export declare const provide: {
      * 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.
      *
-     * @example
+     * **Example** (Providing layer dependencies)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1467,8 +1531,8 @@ export declare const provide: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @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]>>>;
     /**
@@ -1476,7 +1540,8 @@ export declare const provide: {
      * 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.
      *
-     * @example
+     * **Example** (Providing layer dependencies)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1534,8 +1599,8 @@ export declare const provide: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @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>>;
     /**
@@ -1543,7 +1608,8 @@ export declare const provide: {
      * 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.
      *
-     * @example
+     * **Example** (Providing layer dependencies)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1601,8 +1667,8 @@ export declare const provide: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @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]>>>;
 };
@@ -1611,7 +1677,8 @@ export declare const provide: {
  * layer, resulting in a new layer with the inputs of this layer, and the
  * outputs of both layers.
  *
- * @example
+ * **Example** (Providing dependencies while retaining services)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -1675,8 +1742,8 @@ export declare const provide: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const provideMerge: {
     /**
@@ -1684,7 +1751,8 @@ export declare const provideMerge: {
      * layer, resulting in a new layer with the inputs of this layer, and the
      * outputs of both layers.
      *
-     * @example
+     * **Example** (Providing dependencies while retaining services)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1748,8 +1816,8 @@ export declare const provideMerge: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @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>>;
     /**
@@ -1757,7 +1825,8 @@ export declare const provideMerge: {
      * layer, resulting in a new layer with the inputs of this layer, and the
      * outputs of both layers.
      *
-     * @example
+     * **Example** (Providing dependencies while retaining services)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1821,8 +1890,8 @@ export declare const provideMerge: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @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]>>>;
     /**
@@ -1830,7 +1899,8 @@ export declare const provideMerge: {
      * layer, resulting in a new layer with the inputs of this layer, and the
      * outputs of both layers.
      *
-     * @example
+     * **Example** (Providing dependencies while retaining services)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1894,8 +1964,8 @@ export declare const provideMerge: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @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>>;
     /**
@@ -1903,7 +1973,8 @@ export declare const provideMerge: {
      * layer, resulting in a new layer with the inputs of this layer, and the
      * outputs of both layers.
      *
-     * @example
+     * **Example** (Providing dependencies while retaining services)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -1967,15 +2038,16 @@ export declare const provideMerge: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @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]> | Exclude<R, Success<Layers[number]>>>;
 };
 /**
  * Constructs a layer dynamically based on the output of this layer.
  *
- * @example
+ * **Example** (Creating services from layer output)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -2039,14 +2111,15 @@ export declare const provideMerge: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const flatMap: {
     /**
      * Constructs a layer dynamically based on the output of this layer.
      *
-     * @example
+     * **Example** (Creating services from layer output)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -2110,14 +2183,15 @@ export declare const flatMap: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <A, A2, E2, R2>(f: (context: Context.Context<A>) => Layer<A2, E2, R2>): <E, R>(self: Layer<A, E, R>) => Layer<A2, E2 | E, R2 | R>;
     /**
      * Constructs a layer dynamically based on the output of this layer.
      *
-     * @example
+     * **Example** (Creating services from layer output)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -2181,57 +2255,63 @@ export declare const flatMap: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <A, E, R, A2, E2, R2>(self: Layer<A, E, R>, f: (context: Context.Context<A>) => Layer<A2, E2, R2>): Layer<A2, E | E2, R | R2>;
 };
 /**
  * Performs the specified effect if this layer succeeds.
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export declare const tap: {
     /**
      * Performs the specified effect if this layer succeeds.
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <ROut, XR extends ROut, RIn2, E2, X>(f: (context: Context.Context<XR>) => Effect<X, E2, RIn2>): <RIn, E>(self: Layer<ROut, E, RIn>) => Layer<ROut, E | E2, RIn | Exclude<RIn2, Scope.Scope>>;
     /**
      * Performs the specified effect if this layer succeeds.
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <RIn, E, ROut, XR extends ROut, RIn2, E2, X>(self: Layer<ROut, E, RIn>, f: (context: Context.Context<XR>) => Effect<X, E2, RIn2>): Layer<ROut, E | E2, RIn | Exclude<RIn2, Scope.Scope>>;
 };
 /**
  * Performs the specified effect if this layer fails.
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export declare const tapError: {
     /**
      * Performs the specified effect if this layer fails.
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <E, XE extends E, RIn2, E2, X>(f: (e: XE) => Effect<X, E2, RIn2>): <RIn, ROut>(self: Layer<ROut, E, RIn>) => Layer<ROut, E | E2, RIn | Exclude<RIn2, Scope.Scope>>;
     /**
      * Performs the specified effect if this layer fails.
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <RIn, E, XE extends E, ROut, RIn2, E2, X>(self: Layer<ROut, E, RIn>, f: (e: XE) => Effect<X, E2, RIn2>): Layer<ROut, E | E2, RIn | Exclude<RIn2, Scope.Scope>>;
 };
 /**
- * Performs the specified effect if this layer fails.
+ * 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
+ * added to the layer's error type.
  *
  * **Previously Known As**
  *
@@ -2239,12 +2319,18 @@ export declare const tapError: {
  *
  * - `Layer.tapErrorCause`
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export declare const tapCause: {
     /**
-     * Performs the specified effect if this layer fails.
+     * 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
+     * added to the layer's error type.
      *
      * **Previously Known As**
      *
@@ -2252,12 +2338,18 @@ export declare const tapCause: {
      *
      * - `Layer.tapErrorCause`
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <E, XE extends E, RIn2, E2, X>(f: (cause: Cause.Cause<XE>) => Effect<X, E2, RIn2>): <RIn, ROut>(self: Layer<ROut, E, RIn>) => Layer<ROut, E | E2, RIn | Exclude<RIn2, Scope.Scope>>;
     /**
-     * Performs the specified effect if this layer fails.
+     * 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
+     * added to the layer's error type.
      *
      * **Previously Known As**
      *
@@ -2265,8 +2357,8 @@ export declare const tapCause: {
      *
      * - `Layer.tapErrorCause`
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <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>>;
 };
@@ -2274,7 +2366,8 @@ export declare const tapCause: {
  * Translates effect failure into death of the fiber, making all failures
  * unchecked and not a part of the type of the layer.
  *
- * @example
+ * **Example** (Converting layer failures to defects)
+ *
  * ```ts
  * import { Data, Effect, Layer, Context } from "effect"
  *
@@ -2288,13 +2381,8 @@ export declare const tapCause: {
  *
  * // Layer that can fail during construction
  * const flakyDatabaseLayer = Layer.effect(Database)(Effect.gen(function*() {
- *   // Simulate a database connection that might fail
- *   const shouldFail = Math.random() > 0.5
- *   if (shouldFail) {
- *     return yield* new DatabaseError({ message: "Connection failed" })
- *   }
- *
- *   return { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result: ${sql}`)) }
+ *   console.log("connecting")
+ *   return yield* new DatabaseError({ message: "Connection failed" })
  * }))
  *
  * // Convert failures to fiber death - removes error from type
@@ -2308,12 +2396,12 @@ export declare const tapCause: {
  *   Effect.provide(reliableDatabaseLayer)
  * )
  *
- * // If the database layer fails, the entire fiber will die
- * // instead of the effect failing with DatabaseError
+ * // Running the program prints "connecting", then the DatabaseError is
+ * // converted into a fiber defect instead of remaining a typed error.
  * ```
  *
- * @since 2.0.0
  * @category error handling
+ * @since 2.0.0
  */
 export declare const orDie: <A, E, R>(self: Layer<A, E, R>) => Layer<A, never, R>;
 declare const catch_: {
@@ -2324,14 +2412,15 @@ export {
 /**
  * Recovers from all errors.
  *
- * @since 4.0.0
  * @category error handling
+ * @since 4.0.0
  */
 catch_ as catch };
 /**
  * Recovers from specific tagged errors.
  *
- * @example
+ * **Example** (Recovering from tagged layer errors)
+ *
  * ```ts
  * import { Data, Effect, Layer, Context } from "effect"
  *
@@ -2350,14 +2439,15 @@ catch_ as catch };
  * )
  * ```
  *
- * @since 4.0.0
  * @category error handling
+ * @since 4.0.0
  */
 export declare const catchTag: {
     /**
      * Recovers from specific tagged errors.
      *
-     * @example
+     * **Example** (Recovering from tagged layer errors)
+     *
      * ```ts
      * import { Data, Effect, Layer, Context } from "effect"
      *
@@ -2376,14 +2466,15 @@ export declare const catchTag: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <const K extends Types.Tags<E> | NonEmptyReadonlyArray<Types.Tags<E>>, E, RIn2, E2, ROut2>(k: K, f: (e: Types.ExtractTag<Types.NoInfer<E>, K extends NonEmptyReadonlyArray<string> ? K[number] : K>) => Layer<ROut2, E2, RIn2>): <RIn, ROut>(self: Layer<ROut, E, RIn>) => Layer<ROut & ROut2, E2 | Types.ExcludeTag<E, K extends NonEmptyReadonlyArray<string> ? K[number] : K>, RIn2 | RIn>;
     /**
      * Recovers from specific tagged errors.
      *
-     * @example
+     * **Example** (Recovering from tagged layer errors)
+     *
      * ```ts
      * import { Data, Effect, Layer, Context } from "effect"
      *
@@ -2402,15 +2493,21 @@ export declare const catchTag: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <RIn, E, ROut, const K extends Types.Tags<E> | NonEmptyReadonlyArray<Types.Tags<E>>, RIn2, E2, ROut2>(self: Layer<ROut, E, RIn>, k: K, f: (e: Types.ExtractTag<E, K extends NonEmptyReadonlyArray<string> ? K[number] : K>) => Layer<ROut2, E2, RIn2>): Layer<ROut & ROut2, E2 | Types.ExcludeTag<E, K extends NonEmptyReadonlyArray<string> ? K[number] : K>, RIn | RIn2>;
 };
 /**
- * Recovers from all errors.
+ * Recovers from any failure cause by switching to another layer.
+ *
+ * **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.
+ *
+ * **Example** (Recovering from layer failures by cause)
  *
- * @example
  * ```ts
  * import { Data, Effect, Layer, Context } from "effect"
  *
@@ -2418,57 +2515,48 @@ export declare const catchTag: {
  *   message: string
  * }> {}
  *
- * class NetworkError extends Data.TaggedError("NetworkError")<{
- *   reason: string
- * }> {}
- *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
- * class Logger extends Context.Service<Logger, {
- *   readonly log: (msg: string) => Effect.Effect<void>
- * }>()("Logger") {}
- *
- * // Primary database layer that might fail
- * const primaryDatabaseLayer = Layer.effect(Database)(Effect.gen(function*() {
- *   return yield* new DatabaseError({ message: "Primary DB unreachable" })
- *   return { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Primary: ${sql}`)) }
- * }))
+ * const primaryDatabaseLayer = Layer.effect(Database)(
+ *   Effect.fail(new DatabaseError({ message: "Primary DB unreachable" }))
+ * )
  *
- * // Fallback layers for different error causes
  * const databaseWithFallback = primaryDatabaseLayer.pipe(
  *   Layer.catchCause(() => {
- *     // For any cause/error, fallback to in-memory database
- *     return Layer.mergeAll(
- *       Layer.succeed(Database)({
- *         query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
- *       }),
- *       Layer.succeed(Logger)({
- *         log: Effect.fn("Logger.log")((msg: string) =>
- *           Effect.sync(() => console.log(`[FALLBACK] ${msg}`))
- *         )
- *       })
- *     )
+ *     return Layer.succeed(Database)({
+ *       query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
+ *     })
  *   })
  * )
  *
  * const program = Effect.gen(function*() {
  *   const database = yield* Database
- *   return yield* database.query("SELECT * FROM users")
+ *   const result = yield* database.query("SELECT * FROM users")
+ *   console.log(result)
  * }).pipe(
  *   Effect.provide(databaseWithFallback)
  * )
+ *
+ * Effect.runPromise(program)
+ * // Memory: SELECT * FROM users
  * ```
  *
- * @since 2.0.0
  * @category error handling
+ * @since 2.0.0
  */
 export declare const catchCause: {
     /**
-     * Recovers from all errors.
+     * Recovers from any failure cause by switching to another layer.
+     *
+     * **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.
+     *
+     * **Example** (Recovering from layer failures by cause)
      *
-     * @example
      * ```ts
      * import { Data, Effect, Layer, Context } from "effect"
      *
@@ -2476,57 +2564,48 @@ export declare const catchCause: {
      *   message: string
      * }> {}
      *
-     * class NetworkError extends Data.TaggedError("NetworkError")<{
-     *   reason: string
-     * }> {}
-     *
      * class Database extends Context.Service<Database, {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * class Logger extends Context.Service<Logger, {
-     *   readonly log: (msg: string) => Effect.Effect<void>
-     * }>()("Logger") {}
-     *
-     * // Primary database layer that might fail
-     * const primaryDatabaseLayer = Layer.effect(Database)(Effect.gen(function*() {
-     *   return yield* new DatabaseError({ message: "Primary DB unreachable" })
-     *   return { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Primary: ${sql}`)) }
-     * }))
+     * const primaryDatabaseLayer = Layer.effect(Database)(
+     *   Effect.fail(new DatabaseError({ message: "Primary DB unreachable" }))
+     * )
      *
-     * // Fallback layers for different error causes
      * const databaseWithFallback = primaryDatabaseLayer.pipe(
      *   Layer.catchCause(() => {
-     *     // For any cause/error, fallback to in-memory database
-     *     return Layer.mergeAll(
-     *       Layer.succeed(Database)({
-     *         query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
-     *       }),
-     *       Layer.succeed(Logger)({
-     *         log: Effect.fn("Logger.log")((msg: string) =>
-     *           Effect.sync(() => console.log(`[FALLBACK] ${msg}`))
-     *         )
-     *       })
-     *     )
+     *     return Layer.succeed(Database)({
+     *       query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
+     *     })
      *   })
      * )
      *
      * const program = Effect.gen(function*() {
      *   const database = yield* Database
-     *   return yield* database.query("SELECT * FROM users")
+     *   const result = yield* database.query("SELECT * FROM users")
+     *   console.log(result)
      * }).pipe(
      *   Effect.provide(databaseWithFallback)
      * )
+     *
+     * Effect.runPromise(program)
+     * // Memory: SELECT * FROM users
      * ```
      *
-     * @since 2.0.0
      * @category error handling
+     * @since 2.0.0
      */
     <E, RIn2, E2, ROut2>(onError: (cause: Cause.Cause<E>) => Layer<ROut2, E2, RIn2>): <RIn, ROut>(self: Layer<ROut, E, RIn>) => Layer<ROut & ROut2, E2, RIn2 | RIn>;
     /**
-     * Recovers from all errors.
+     * Recovers from any failure cause by switching to another layer.
+     *
+     * **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.
+     *
+     * **Example** (Recovering from layer failures by cause)
      *
-     * @example
      * ```ts
      * import { Data, Effect, Layer, Context } from "effect"
      *
@@ -2534,51 +2613,36 @@ export declare const catchCause: {
      *   message: string
      * }> {}
      *
-     * class NetworkError extends Data.TaggedError("NetworkError")<{
-     *   reason: string
-     * }> {}
-     *
      * class Database extends Context.Service<Database, {
      *   readonly query: (sql: string) => Effect.Effect<string>
      * }>()("Database") {}
      *
-     * class Logger extends Context.Service<Logger, {
-     *   readonly log: (msg: string) => Effect.Effect<void>
-     * }>()("Logger") {}
-     *
-     * // Primary database layer that might fail
-     * const primaryDatabaseLayer = Layer.effect(Database)(Effect.gen(function*() {
-     *   return yield* new DatabaseError({ message: "Primary DB unreachable" })
-     *   return { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Primary: ${sql}`)) }
-     * }))
+     * const primaryDatabaseLayer = Layer.effect(Database)(
+     *   Effect.fail(new DatabaseError({ message: "Primary DB unreachable" }))
+     * )
      *
-     * // Fallback layers for different error causes
      * const databaseWithFallback = primaryDatabaseLayer.pipe(
      *   Layer.catchCause(() => {
-     *     // For any cause/error, fallback to in-memory database
-     *     return Layer.mergeAll(
-     *       Layer.succeed(Database)({
-     *         query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
-     *       }),
-     *       Layer.succeed(Logger)({
-     *         log: Effect.fn("Logger.log")((msg: string) =>
-     *           Effect.sync(() => console.log(`[FALLBACK] ${msg}`))
-     *         )
-     *       })
-     *     )
+     *     return Layer.succeed(Database)({
+     *       query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
+     *     })
      *   })
      * )
      *
      * const program = Effect.gen(function*() {
      *   const database = yield* Database
-     *   return yield* database.query("SELECT * FROM users")
+     *   const result = yield* database.query("SELECT * FROM users")
+     *   console.log(result)
      * }).pipe(
      *   Effect.provide(databaseWithFallback)
      * )
+     *
+     * Effect.runPromise(program)
+     * // Memory: SELECT * FROM users
      * ```
      *
-     * @since 2.0.0
      * @category error handling
+     * @since 2.0.0
      */
     <RIn, E, ROut, RIn2, E2, ROut22>(self: Layer<ROut, E, RIn>, onError: (cause: Cause.Cause<E>) => Layer<ROut22, E2, RIn2>): Layer<ROut & ROut22, E2, RIn | RIn2>;
 };
@@ -2597,8 +2661,8 @@ export declare const catchCause: {
  * This is useful for adapting or extending a service's behavior during the
  * creation of a layer.
  *
- * @since 3.13.0
  * @category utils
+ * @since 3.13.0
  */
 export declare const updateService: {
     /**
@@ -2616,8 +2680,8 @@ export declare const updateService: {
      * This is useful for adapting or extending a service's behavior during the
      * creation of a layer.
      *
-     * @since 3.13.0
      * @category utils
+     * @since 3.13.0
      */
     <I, A>(service: Context.Key<I, A>, f: (a: Types.NoInfer<A>) => A): <A1, E1, R1>(layer: Layer<A1, E1, R1>) => Layer<A1, E1, I | R1>;
     /**
@@ -2635,68 +2699,90 @@ export declare const updateService: {
      * This is useful for adapting or extending a service's behavior during the
      * creation of a layer.
      *
-     * @since 3.13.0
      * @category utils
+     * @since 3.13.0
      */
     <A1, E1, R1, I, A>(layer: Layer<A1, E1, R1>, service: Context.Key<I, A>, f: (a: Types.NoInfer<A>) => A): Layer<A1, E1, I | R1>;
 };
 /**
  * Creates a fresh version of this layer that will not be shared.
  *
- * @example
+ * **Example** (Creating non-shared layer instances)
+ *
  * ```ts
  * import { Effect, Layer, Ref, Context } from "effect"
  *
  * class Counter extends Context.Service<Counter, {
- *   readonly count: number
- *   readonly increment: () => Effect.Effect<number>
+ *   readonly id: number
  * }>()("Counter") {}
  *
- * // Layer that creates a counter with shared state
- * const counterLayer = Layer.effect(Counter)(Effect.gen(function*() {
- *   const ref = yield* Ref.make(0)
- *   return {
- *     count: 0,
- *     increment: Effect.fn("Counter.increment")(() =>
- *       Ref.update(ref, (n) => n + 1).pipe(
- *         Effect.flatMap(() => Ref.get(ref))
- *       )
- *     )
- *   }
+ * class Left extends Context.Service<Left, {
+ *   readonly counterId: number
+ * }>()("Left") {}
+ *
+ * class Right extends Context.Service<Right, {
+ *   readonly counterId: number
+ * }>()("Right") {}
+ *
+ * const leftLayer = Layer.effect(Left)(Effect.gen(function*() {
+ *   const counter = yield* Counter
+ *   return { counterId: counter.id }
  * }))
  *
- * // By default, layers are shared - same instance used everywhere
- * const sharedProgram = Effect.gen(function*() {
- *   const counter1 = yield* Counter
- *   const counter2 = yield* Counter
+ * const rightLayer = Layer.effect(Right)(Effect.gen(function*() {
+ *   const counter = yield* Counter
+ *   return { counterId: counter.id }
+ * }))
  *
- *   // Both counter1 and counter2 refer to the same instance
- *   console.log("Shared layer - same instance")
- * }).pipe(
- *   Effect.provide(counterLayer)
- * )
+ * const showIds = Effect.gen(function*() {
+ *   const left = yield* Left
+ *   const right = yield* Right
+ *   console.log(`same Counter: ${left.counterId === right.counterId}`)
+ * })
  *
- * // Fresh layer creates a new instance each time
- * const freshProgram = Effect.gen(function*() {
- *   const counter1 = yield* Counter
- *   const counter2 = yield* Counter
+ * const program = Effect.gen(function*() {
+ *   const nextId = yield* Ref.make(0)
  *
- *   // counter1 and counter2 are different instances
- *   console.log("Fresh layer - different instances")
- * }).pipe(
- *   Effect.provide(Layer.fresh(counterLayer))
- * )
+ *   const counterLayer = Layer.effect(Counter)(Effect.gen(function*() {
+ *     const id = yield* Ref.updateAndGet(nextId, (n) => n + 1)
+ *     console.log("constructed Counter")
+ *     return { id }
+ *   }))
+ *
+ *   const shared = Layer.merge(
+ *     Layer.provide(leftLayer, counterLayer),
+ *     Layer.provide(rightLayer, counterLayer)
+ *   )
+ *
+ *   yield* Effect.provide(showIds, shared)
+ *
+ *   const freshCounterLayer = Layer.fresh(counterLayer)
+ *   const fresh = Layer.merge(
+ *     Layer.provide(leftLayer, freshCounterLayer),
+ *     Layer.provide(rightLayer, freshCounterLayer)
+ *   )
+ *
+ *   yield* Effect.provide(showIds, fresh)
+ * })
+ *
+ * Effect.runPromise(program)
+ * // constructed Counter
+ * // same Counter: true
+ * // constructed Counter
+ * // constructed Counter
+ * // same Counter: false
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 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.
  *
- * @example
+ * **Example** (Launching an application layer)
+ *
  * ```ts
  * import { Console, Effect, Layer, Context } from "effect"
  *
@@ -2743,8 +2829,8 @@ export declare const fresh: <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, R>;
  * // Effect.runFork(application)
  * ```
  *
- * @since 2.0.0
  * @category conversions
+ * @since 2.0.0
  */
 export declare const launch: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<never, E, RIn>;
 /**
@@ -2754,8 +2840,8 @@ export declare const launch: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect
  * while keeping non-Effect properties required. This allows you to provide
  * only the methods you need to test while leaving others unimplemented.
  *
- * @since 4.0.0
  * @category Testing
+ * @since 4.0.0
  */
 export type PartialEffectful<A extends object> = Types.Simplify<{
     [K in keyof A as A[K] extends AnyEffectOrStream ? K : never]?: A[K];
@@ -2768,7 +2854,8 @@ type AnyEffectOrStream = Effect<any, any, any> | Stream.Stream<any, any, any> |
  * implementation of the service, and any methods not provided will
  * throw an unimplemented defect when called.
  *
- * @example
+ * **Example** (Mocking services for tests)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -2806,8 +2893,8 @@ type AnyEffectOrStream = Effect<any, any, any> | Stream.Stream<any, any, any> |
  * )
  * ```
  *
- * @since 4.0.0
  * @category Testing
+ * @since 4.0.0
  */
 export declare const mock: {
     /**
@@ -2815,7 +2902,8 @@ export declare const mock: {
      * implementation of the service, and any methods not provided will
      * throw an unimplemented defect when called.
      *
-     * @example
+     * **Example** (Mocking services for tests)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -2853,8 +2941,8 @@ export declare const mock: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category Testing
+     * @since 4.0.0
      */
     <I, S extends object>(service: Context.Key<I, S>): (implementation: PartialEffectful<S>) => Layer<I>;
     /**
@@ -2862,7 +2950,8 @@ export declare const mock: {
      * implementation of the service, and any methods not provided will
      * throw an unimplemented defect when called.
      *
-     * @example
+     * **Example** (Mocking services for tests)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -2900,8 +2989,8 @@ export declare const mock: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category Testing
+     * @since 4.0.0
      */
     <I, S extends object>(service: Context.Key<I, S>, implementation: Types.NoInfer<PartialEffectful<S>>): Layer<I>;
 };
@@ -2911,7 +3000,8 @@ export declare const mock: {
  * This function provides compile-time type checking to ensure that the success
  * value of an layer conforms to a specific type constraint.
  *
- * @example
+ * **Example** (Constraining layer success types)
+ *
  * ```ts
  * import { Layer } from "effect"
  *
@@ -2927,11 +3017,11 @@ export declare const mock: {
  * // This would cause a TypeScript compilation error:
  * // const invalidLayer = satisfiesNumber(StringLayer)
  * //                                     ^^^^^^^^^^^
- * // Type 'number' is not assignable to type 'string'
+ * // Type 'string' is not assignable to type 'number'
  * ```
  *
- * @since 4.0.0
  * @category Type constraints
+ * @since 4.0.0
  */
 export declare const satisfiesSuccessType: <ROut>() => <ROut2 extends ROut, E, RIn>(layer: Layer<ROut2, E, RIn>) => Layer<ROut2, E, RIn>;
 /**
@@ -2940,7 +3030,8 @@ export declare const satisfiesSuccessType: <ROut>() => <ROut2 extends ROut, E, R
  * This function provides compile-time type checking to ensure that the error
  * type of an layer conforms to a specific type constraint.
  *
- * @example
+ * **Example** (Constraining layer error types)
+ *
  * ```ts
  * import { Layer } from "effect"
  *
@@ -2960,8 +3051,8 @@ export declare const satisfiesSuccessType: <ROut>() => <ROut2 extends ROut, E, R
  * // Type 'string' is not assignable to type 'Error'
  * ```
  *
- * @since 4.0.0
  * @category Type constraints
+ * @since 4.0.0
  */
 export declare const satisfiesErrorType: <E>() => <ROut, E2 extends E, RIn>(layer: Layer<ROut, E2, RIn>) => Layer<ROut, E2, RIn>;
 /**
@@ -2970,14 +3061,15 @@ export declare const satisfiesErrorType: <E>() => <ROut, E2 extends E, RIn>(laye
  * This function provides compile-time type checking to ensure that the
  * requirements (context) type of an layer conforms to a specific type constraint.
  *
- * @example
+ * **Example** (Constraining layer service requirements)
+ *
  * ```ts
  * import { Layer } from "effect"
  *
  * declare const FortyTwoLayer: Layer.Layer<never, never, 42>
  * declare const StringLayer: Layer.Layer<never, never, string>
  *
- * // Define a constraint that the success type must be a number
+ * // Define a constraint that the service requirements must be numbers
  * const satisfiesNumber = Layer.satisfiesServicesType<number>()
  *
  * // This works - Layer<never, never, 42> extends Layer<never, never, number>
@@ -2989,16 +3081,16 @@ export declare const satisfiesErrorType: <E>() => <ROut, E2 extends E, RIn>(laye
  * // Type 'string' is not assignable to type 'number'
  * ```
  *
- * @since 4.0.0
  * @category Type constraints
+ * @since 4.0.0
  */
 export declare const satisfiesServicesType: <RIn>() => <ROut, E, RIn2 extends RIn>(layer: Layer<ROut, E, RIn2>) => Layer<ROut, E, RIn2>;
 /**
  * Represents options that can be used to control the behavior of spans created
  * for layers.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface SpanOptions extends Tracer.SpanOptions {
     /**
@@ -3015,7 +3107,8 @@ export interface SpanOptions extends Tracer.SpanOptions {
  * operations within the layer constructor part of the same trace span. The span
  * is automatically closed when the layer's scope is closed.
  *
- * @example
+ * **Example** (Tracing layer construction with a span)
+ *
  * ```ts
  * import { Console, Effect, Layer, Context, type Tracer } from "effect"
  *
@@ -3049,19 +3142,20 @@ export interface SpanOptions extends Tracer.SpanOptions {
  * })
  * ```
  *
- * @since 4.0.0
  * @category tracing
+ * @since 4.0.0
  */
 export declare const span: (name: string, options?: SpanOptions) => Layer<Tracer.ParentSpan>;
 /**
- * Constructs a new `Layer` which takes an existing span and registers it as the
- * current parent span.
+ * Constructs a layer that provides an existing span as the current parent span.
  *
- * 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.
+ * **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.
+ *
+ * **Example** (Using an existing parent span)
  *
- * @example
  * ```ts
  * import { Console, Effect, Layer, Context, Tracer } from "effect"
  *
@@ -3088,8 +3182,8 @@ export declare const span: (name: string, options?: SpanOptions) => Layer<Tracer
  * }))))
  * ```
  *
- * @since 4.0.0
  * @category tracing
+ * @since 4.0.0
  */
 export declare const parentSpan: (span: Tracer.AnySpan) => Layer<Tracer.ParentSpan>;
 /**
@@ -3100,7 +3194,8 @@ export declare const parentSpan: (span: Tracer.AnySpan) => Layer<Tracer.ParentSp
  * is automatically ended when the layer's scope is closed. This is useful for
  * tracking the lifecycle and performance of layer initialization.
  *
- * @example
+ * **Example** (Wrapping a layer with a span)
+ *
  * ```ts
  * import { Effect, Layer, Context } from "effect"
  *
@@ -3147,8 +3242,8 @@ export declare const parentSpan: (span: Tracer.AnySpan) => Layer<Tracer.ParentSp
  * )
  * ```
  *
- * @since 4.0.0
  * @category tracing
+ * @since 4.0.0
  */
 export declare const withSpan: {
     /**
@@ -3159,7 +3254,8 @@ export declare const withSpan: {
      * is automatically ended when the layer's scope is closed. This is useful for
      * tracking the lifecycle and performance of layer initialization.
      *
-     * @example
+     * **Example** (Wrapping a layer with a span)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -3206,8 +3302,8 @@ export declare const withSpan: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category tracing
+     * @since 4.0.0
      */
     (name: string, options?: SpanOptions): <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, Exclude<R, Tracer.ParentSpan>>;
     /**
@@ -3218,7 +3314,8 @@ export declare const withSpan: {
      * is automatically ended when the layer's scope is closed. This is useful for
      * tracking the lifecycle and performance of layer initialization.
      *
-     * @example
+     * **Example** (Wrapping a layer with a span)
+     *
      * ```ts
      * import { Effect, Layer, Context } from "effect"
      *
@@ -3265,19 +3362,21 @@ export declare const withSpan: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category tracing
+     * @since 4.0.0
      */
     <A, E, R>(self: Layer<A, E, R>, name: string, options?: SpanOptions): Layer<A, E, Exclude<R, Tracer.ParentSpan>>;
 };
 /**
- * Wraps a `Layer` with a new tracing span and sets the span as the parent span.
+ * Wraps a layer so spans created during its construction use the supplied span
+ * as their parent.
  *
- * This attaches a layer to an existing trace span, making all operations within
- * the layer children of the provided parent span. This is useful for integrating
- * layer construction into an existing trace hierarchy.
+ * **Details**
+ * Use this to attach layer construction to an existing trace hierarchy. This API
+ * does not create or end the supplied parent span.
+ *
+ * **Example** (Attaching layers to an existing parent span)
  *
- * @example
  * ```ts
  * import { Effect, Layer, Context, Tracer } from "effect"
  *
@@ -3326,18 +3425,20 @@ export declare const withSpan: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category tracing
+ * @since 4.0.0
  */
 export declare const withParentSpan: {
     /**
-     * Wraps a `Layer` with a new tracing span and sets the span as the parent span.
+     * Wraps a layer so spans created during its construction use the supplied span
+     * as their parent.
      *
-     * This attaches a layer to an existing trace span, making all operations within
-     * the layer children of the provided parent span. This is useful for integrating
-     * layer construction into an existing trace hierarchy.
+     * **Details**
+     * Use this to attach layer construction to an existing trace hierarchy. This API
+     * does not create or end the supplied parent span.
+     *
+     * **Example** (Attaching layers to an existing parent span)
      *
-     * @example
      * ```ts
      * import { Effect, Layer, Context, Tracer } from "effect"
      *
@@ -3386,18 +3487,20 @@ export declare const withParentSpan: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category tracing
+     * @since 4.0.0
      */
     (span: Tracer.AnySpan, options?: Tracer.TraceOptions): <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, Exclude<R, Tracer.ParentSpan>>;
     /**
-     * Wraps a `Layer` with a new tracing span and sets the span as the parent span.
+     * Wraps a layer so spans created during its construction use the supplied span
+     * 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.
      *
-     * This attaches a layer to an existing trace span, making all operations within
-     * the layer children of the provided parent span. This is useful for integrating
-     * layer construction into an existing trace hierarchy.
+     * **Example** (Attaching layers to an existing parent span)
      *
-     * @example
      * ```ts
      * import { Effect, Layer, Context, Tracer } from "effect"
      *
@@ -3446,8 +3549,8 @@ export declare const withParentSpan: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category tracing
+     * @since 4.0.0
      */
     <A, E, R>(self: Layer<A, E, R>, span: Tracer.AnySpan, options?: Tracer.TraceOptions): Layer<A, E, Exclude<R, Tracer.ParentSpan>>;
 };