effect 4.0.0-beta.73 → 4.0.0-beta.75

package/dist/Latch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Latch.d.ts","sourceRoot":"","sources":["../src/Latch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Latch.d.ts","sourceRoot":"","sources":["../src/Latch.ts"],"names":[],"mappings":"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"}

package/dist/Latch.js

@@ -4,7 +4,8 @@ import * as internal from "./internal/effect.js";
  *
  * **When to use**
  *
- * Use when synchronous allocation is required outside an Effect workflow.
+ * Use when you need to allocate a `Latch` synchronously outside an Effect
+ * workflow.
  *
  * **Details**
  *
@@ -103,8 +104,8 @@ export const open = self => self.open;
  *
  * **When to use**
  *
- * Use when synchronous code needs to open a latch immediately and release the
- * fibers waiting on it.
+ * Use when you need synchronous code to open a latch immediately and release
+ * the fibers waiting on it.
  *
  * **Details**
  *

package/dist/Latch.js.map

@@ -1 +1 @@
-{"version":3,"file":"Latch.js","names":["internal","makeUnsafe","makeLatchUnsafe","make","makeLatch","open","self","openUnsafe","release","_await","await","close","closeUnsafe","whenOpen","args","length","effect"],"sources":["../src/Latch.ts"],"sourcesContent":[null],"mappings":"AAoCA,OAAO,KAAKA,QAAQ,MAAM,sBAAsB;AA2GhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,OAAO,MAAMC,UAAU,GAA0CD,QAAQ,CAACE,eAAe;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,OAAO,MAAMC,IAAI,GAAyDH,QAAQ,CAACI,SAAS;AAE5F;;;;;;;;;;;;;;;;;;AAkBA,OAAO,MAAMC,IAAI,GAAIC,IAAW,IAA6BA,IAAI,CAACD,IAAI;AAEtE;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAME,UAAU,GAAID,IAAW,IAAcA,IAAI,CAACC,UAAU,EAAE;AAErE;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,MAAMC,OAAO,GAAIF,IAAW,IAA6BA,IAAI,CAACE,OAAO;AAE5E,MAAMC,MAAM,GAAIH,IAAW,IAA0BA,IAAI,CAACI,KAAK;AAE/D;AACE;;;;;;;;;;;;;;;;;;;;;;;;;AAyBAD,MAAM,IAAIC,KAAK;AAGjB;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,MAAMC,KAAK,GAAIL,IAAW,IAA6BA,IAAI,CAACK,KAAK;AAExE;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMC,WAAW,GAAIN,IAAW,IAAcA,IAAI,CAACM,WAAW,EAAE;AAEvE;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMC,QAAQ,GA+ChBA,CAAC,GAAGC,IAAgB,KAAI;EAC3B,IAAIA,IAAI,CAACC,MAAM,KAAK,CAAC,EAAE;IACrB,MAAM,CAACT,IAAI,CAAC,GAAGQ,IAAI;IACnB,OAAQE,MAAoC,IAAKV,IAAI,CAACO,QAAQ,CAACG,MAAM,CAAC;EACxE;EACA,MAAM,CAACV,IAAI,EAAEU,MAAM,CAAC,GAAGF,IAAI;EAC3B,OAAOR,IAAI,CAACO,QAAQ,CAACG,MAAM,CAAC;AAC9B,CAAS","ignoreList":[]}
+{"version":3,"file":"Latch.js","names":["internal","makeUnsafe","makeLatchUnsafe","make","makeLatch","open","self","openUnsafe","release","_await","await","close","closeUnsafe","whenOpen","args","length","effect"],"sources":["../src/Latch.ts"],"sourcesContent":[null],"mappings":"AAoCA,OAAO,KAAKA,QAAQ,MAAM,sBAAsB;AA2GhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,OAAO,MAAMC,UAAU,GAA0CD,QAAQ,CAACE,eAAe;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,OAAO,MAAMC,IAAI,GAAyDH,QAAQ,CAACI,SAAS;AAE5F;;;;;;;;;;;;;;;;;;AAkBA,OAAO,MAAMC,IAAI,GAAIC,IAAW,IAA6BA,IAAI,CAACD,IAAI;AAEtE;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAME,UAAU,GAAID,IAAW,IAAcA,IAAI,CAACC,UAAU,EAAE;AAErE;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,MAAMC,OAAO,GAAIF,IAAW,IAA6BA,IAAI,CAACE,OAAO;AAE5E,MAAMC,MAAM,GAAIH,IAAW,IAA0BA,IAAI,CAACI,KAAK;AAE/D;AACE;;;;;;;;;;;;;;;;;;;;;;;;;AAyBAD,MAAM,IAAIC,KAAK;AAGjB;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,MAAMC,KAAK,GAAIL,IAAW,IAA6BA,IAAI,CAACK,KAAK;AAExE;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMC,WAAW,GAAIN,IAAW,IAAcA,IAAI,CAACM,WAAW,EAAE;AAEvE;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMC,QAAQ,GA+ChBA,CAAC,GAAGC,IAAgB,KAAI;EAC3B,IAAIA,IAAI,CAACC,MAAM,KAAK,CAAC,EAAE;IACrB,MAAM,CAACT,IAAI,CAAC,GAAGQ,IAAI;IACnB,OAAQE,MAAoC,IAAKV,IAAI,CAACO,QAAQ,CAACG,MAAM,CAAC;EACxE;EACA,MAAM,CAACV,IAAI,EAAEU,MAAM,CAAC,GAAGF,IAAI;EAC3B,OAAOR,IAAI,CAACO,QAAQ,CAACG,MAAM,CAAC;AAC9B,CAAS","ignoreList":[]}

package/dist/Layer.d.ts

@@ -768,9 +768,8 @@ export declare const buildWithScope: {
  *
  * **When to use**
  *
- * Use 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.
+ * Use when you need a `Layer` that provides a service from an already
+ * constructed implementation without effectful acquisition.
  *
  * **Example** (Creating a layer from a service implementation)
  *
@@ -798,9 +797,8 @@ export declare const succeed: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need a `Layer` that provides a service from an already
+     * constructed implementation without effectful acquisition.
      *
      * **Example** (Creating a layer from a service implementation)
      *
@@ -828,9 +826,8 @@ export declare const succeed: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need a `Layer` that provides a service from an already
+     * constructed implementation without effectful acquisition.
      *
      * **Example** (Creating a layer from a service implementation)
      *
@@ -859,9 +856,8 @@ export declare const succeed: {
  *
  * **When to use**
  *
- * Use 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.
+ * Use when you need a `Layer` built from an existing `Context`, including when
+ * you need to provide multiple services at once.
  *
  * **Details**
  *
@@ -904,9 +900,7 @@ export declare const succeedContext: <A>(context: Context.Context<A>) => Layer<A
  *
  * **When to use**
  *
- * Use when you 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`.
+ * Use as the no-op branch when conditionally composing layers.
  *
  * **Example** (Disabling optional lifecycle work)
  *
@@ -931,9 +925,8 @@ export declare const empty: Layer<never>;
  *
  * **When to use**
  *
- * Use 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.
+ * Use when you need a `Layer` that provides one service whose value is created
+ * synchronously, but creation should be deferred until the layer is built.
  *
  * **Details**
  *
@@ -965,9 +958,8 @@ export declare const sync: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need a `Layer` that provides one service whose value is created
+     * synchronously, but creation should be deferred until the layer is built.
      *
      * **Details**
      *
@@ -999,9 +991,8 @@ export declare const sync: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need a `Layer` that provides one service whose value is created
+     * synchronously, but creation should be deferred until the layer is built.
      *
      * **Details**
      *
@@ -1034,9 +1025,8 @@ export declare const sync: {
  *
  * **When to use**
  *
- * Use 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.
+ * Use when you need a `Layer` that creates multiple services synchronously but
+ * defers that work until the layer is built.
  *
  * **Details**
  *
@@ -1071,10 +1061,8 @@ export declare const syncContext: <A>(evaluate: LazyArg<Context.Context<A>>) =>
  *
  * **When to use**
  *
- * Use 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.
+ * Use when you need to construct a `Layer`-provided service with an `Effect`,
+ * dependencies, or scoped resource acquisition.
  *
  * **Details**
  *
@@ -1110,10 +1098,8 @@ export declare const effect: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to construct a `Layer`-provided service with an `Effect`,
+     * dependencies, or scoped resource acquisition.
      *
      * **Details**
      *
@@ -1149,10 +1135,8 @@ export declare const effect: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to construct a `Layer`-provided service with an `Effect`,
+     * dependencies, or scoped resource acquisition.
      *
      * **Details**
      *
@@ -1189,8 +1173,8 @@ export declare const effect: {
  *
  * **When to use**
  *
- * Use when effectful construction needs to provide multiple
- * services at once. Use `effect` when the effect produces one service value.
+ * Use when you need a `Layer` that effectfully constructs a `Context` with
+ * multiple services.
  *
  * **Details**
  *
@@ -1227,8 +1211,8 @@ export declare const effectContext: <A, E, R>(effect: Effect<Context.Context<A>,
  *
  * **When to use**
  *
- * Use when 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.
+ * Use when layer construction should run an Effect for its side effects while providing no
+ * services.
  *
  * **Example** (Running an effect during layer construction)
  *
@@ -1305,7 +1289,7 @@ export declare const suspend: <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>) => La
  * const unwrappedLayer = Layer.unwrap(layerEffect)
  * ```
  *
- * @category utils
+ * @category converting
  * @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>>;
@@ -1360,8 +1344,8 @@ export declare const mergeAll: <Layers extends [Layer<never, any, any>, ...Array
  *
  * **When to use**
  *
- * Use when composing from an existing layer in a pipeline. Use
- * `mergeAll` when you already have all layers as separate arguments.
+ * Use to combine an existing `Layer` with another `Layer` or an array of
+ * layers while preserving pipeline style.
  *
  * **Details**
  *
@@ -1404,8 +1388,8 @@ export declare const merge: {
      *
      * **When to use**
      *
-     * Use when composing from an existing layer in a pipeline. Use
-     * `mergeAll` when you already have all layers as separate arguments.
+     * Use to combine an existing `Layer` with another `Layer` or an array of
+     * layers while preserving pipeline style.
      *
      * **Details**
      *
@@ -1448,8 +1432,8 @@ export declare const merge: {
      *
      * **When to use**
      *
-     * Use when composing from an existing layer in a pipeline. Use
-     * `mergeAll` when you already have all layers as separate arguments.
+     * Use to combine an existing `Layer` with another `Layer` or an array of
+     * layers while preserving pipeline style.
      *
      * **Details**
      *
@@ -1492,8 +1476,8 @@ export declare const merge: {
      *
      * **When to use**
      *
-     * Use when composing from an existing layer in a pipeline. Use
-     * `mergeAll` when you already have all layers as separate arguments.
+     * Use to combine an existing `Layer` with another `Layer` or an array of
+     * layers while preserving pipeline style.
      *
      * **Details**
      *
@@ -1536,8 +1520,8 @@ export declare const merge: {
      *
      * **When to use**
      *
-     * Use when composing from an existing layer in a pipeline. Use
-     * `mergeAll` when you already have all layers as separate arguments.
+     * Use to combine an existing `Layer` with another `Layer` or an array of
+     * layers while preserving pipeline style.
      *
      * **Details**
      *
@@ -1581,9 +1565,7 @@ export declare const merge: {
  *
  * **When to use**
  *
- * Use 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.
+ * Use when you need to hide an implementation dependency layer from callers.
  *
  * **Details**
  *
@@ -1651,7 +1633,7 @@ export declare const merge: {
  *
  * @see {@link provideMerge} for retaining the dependency services
  *
- * @category utils
+ * @category providing services
  * @since 2.0.0
  */
 export declare const provide: {
@@ -1661,9 +1643,7 @@ export declare const provide: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to hide an implementation dependency layer from callers.
      *
      * **Details**
      *
@@ -1731,7 +1711,7 @@ export declare const provide: {
      *
      * @see {@link provideMerge} for retaining the dependency services
      *
-     * @category utils
+     * @category providing services
      * @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>>;
@@ -1741,9 +1721,7 @@ export declare const provide: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to hide an implementation dependency layer from callers.
      *
      * **Details**
      *
@@ -1811,7 +1789,7 @@ export declare const provide: {
      *
      * @see {@link provideMerge} for retaining the dependency services
      *
-     * @category utils
+     * @category providing services
      * @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]>>>;
@@ -1821,9 +1799,7 @@ export declare const provide: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to hide an implementation dependency layer from callers.
      *
      * **Details**
      *
@@ -1891,7 +1867,7 @@ export declare const provide: {
      *
      * @see {@link provideMerge} for retaining the dependency services
      *
-     * @category utils
+     * @category providing services
      * @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>>;
@@ -1901,9 +1877,7 @@ export declare const provide: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to hide an implementation dependency layer from callers.
      *
      * **Details**
      *
@@ -1971,7 +1945,7 @@ export declare const provide: {
      *
      * @see {@link provideMerge} for retaining the dependency services
      *
-     * @category utils
+     * @category providing services
      * @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]>>>;
@@ -1982,10 +1956,12 @@ export declare const provide: {
  *
  * **When to use**
  *
- * Use 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.
+ * Use when you need to compose `Layer`s while keeping both the constructed
+ * service and the dependency used to build it available.
+ *
+ * **Details**
+ *
+ * Prefer {@link provide} when the dependency should stay private.
  *
  * **Example** (Providing dependencies while retaining services)
  *
@@ -2054,7 +2030,7 @@ export declare const provide: {
  *
  * @see {@link provide} for keeping dependency services private
  *
- * @category utils
+ * @category providing services
  * @since 2.0.0
  */
 export declare const provideMerge: {
@@ -2064,10 +2040,12 @@ export declare const provideMerge: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to compose `Layer`s while keeping both the constructed
+     * service and the dependency used to build it available.
+     *
+     * **Details**
+     *
+     * Prefer {@link provide} when the dependency should stay private.
      *
      * **Example** (Providing dependencies while retaining services)
      *
@@ -2136,7 +2114,7 @@ export declare const provideMerge: {
      *
      * @see {@link provide} for keeping dependency services private
      *
-     * @category utils
+     * @category providing services
      * @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>>;
@@ -2146,10 +2124,12 @@ export declare const provideMerge: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to compose `Layer`s while keeping both the constructed
+     * service and the dependency used to build it available.
+     *
+     * **Details**
+     *
+     * Prefer {@link provide} when the dependency should stay private.
      *
      * **Example** (Providing dependencies while retaining services)
      *
@@ -2218,7 +2198,7 @@ export declare const provideMerge: {
      *
      * @see {@link provide} for keeping dependency services private
      *
-     * @category utils
+     * @category providing services
      * @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]>>>;
@@ -2228,10 +2208,12 @@ export declare const provideMerge: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to compose `Layer`s while keeping both the constructed
+     * service and the dependency used to build it available.
+     *
+     * **Details**
+     *
+     * Prefer {@link provide} when the dependency should stay private.
      *
      * **Example** (Providing dependencies while retaining services)
      *
@@ -2300,7 +2282,7 @@ export declare const provideMerge: {
      *
      * @see {@link provide} for keeping dependency services private
      *
-     * @category utils
+     * @category providing services
      * @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>>;
@@ -2310,10 +2292,12 @@ export declare const provideMerge: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need to compose `Layer`s while keeping both the constructed
+     * service and the dependency used to build it available.
+     *
+     * **Details**
+     *
+     * Prefer {@link provide} when the dependency should stay private.
      *
      * **Example** (Providing dependencies while retaining services)
      *
@@ -2382,7 +2366,7 @@ export declare const provideMerge: {
      *
      * @see {@link provide} for keeping dependency services private
      *
-     * @category utils
+     * @category providing services
      * @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]>>>;
@@ -2856,9 +2840,8 @@ export {
  *
  * **When to use**
  *
- * Use 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.
+ * Use when every typed `Layer` construction error should use the same
+ * recovery path.
  *
  * @see {@link catchTag} for recovering from specific tagged errors
  * @see {@link catchCause} for recovering with access to the full cause
@@ -2872,9 +2855,7 @@ catch_ as catch };
  *
  * **When to use**
  *
- * Use when only some tagged construction errors should be recovered.
- * Use `catchCause` when recovery depends on defects, interruption, or other
- * cause information.
+ * Use when only some tagged `Layer` construction errors should be recovered.
  *
  * **Example** (Recovering from tagged layer errors)
  *
@@ -2907,9 +2888,7 @@ export declare const catchTag: {
      *
      * **When to use**
      *
-     * Use when only some tagged construction errors should be recovered.
-     * Use `catchCause` when recovery depends on defects, interruption, or other
-     * cause information.
+     * Use when only some tagged `Layer` construction errors should be recovered.
      *
      * **Example** (Recovering from tagged layer errors)
      *
@@ -2942,9 +2921,7 @@ export declare const catchTag: {
      *
      * **When to use**
      *
-     * Use when only some tagged construction errors should be recovered.
-     * Use `catchCause` when recovery depends on defects, interruption, or other
-     * cause information.
+     * Use when only some tagged `Layer` construction errors should be recovered.
      *
      * **Example** (Recovering from tagged layer errors)
      *
@@ -2978,9 +2955,8 @@ export declare const catchTag: {
  *
  * **When to use**
  *
- * Use 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.
+ * Use when you need `Layer` recovery to inspect more than the typed error,
+ * such as defects or interruption information.
  *
  * **Details**
  *
@@ -3037,9 +3013,8 @@ export declare const catchCause: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need `Layer` recovery to inspect more than the typed error,
+     * such as defects or interruption information.
      *
      * **Details**
      *
@@ -3096,9 +3071,8 @@ export declare const catchCause: {
      *
      * **When to use**
      *
-     * Use 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.
+     * Use when you need `Layer` recovery to inspect more than the typed error,
+     * such as defects or interruption information.
      *
      * **Details**
      *
@@ -3166,7 +3140,7 @@ export declare const catchCause: {
  * transformation function `f`, and replaces the old service with the
  * transformed one.
  *
- * @category utils
+ * @category providing services
  * @since 3.13.0
  */
 export declare const updateService: {
@@ -3185,7 +3159,7 @@ export declare const updateService: {
      * transformation function `f`, and replaces the old service with the
      * transformed one.
      *
-     * @category utils
+     * @category providing services
      * @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>;
@@ -3204,7 +3178,7 @@ export declare const updateService: {
      * transformation function `f`, and replaces the old service with the
      * transformed one.
      *
-     * @category utils
+     * @category providing services
      * @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>;
@@ -3214,10 +3188,13 @@ export declare const updateService: {
  *
  * **When to use**
  *
- * Use 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.
+ * Use when you need two parts of an application to receive separate instances
+ * of a resource, such as two independent client sessions.
+ *
+ * **Gotchas**
+ *
+ * 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)
  *
@@ -3285,7 +3262,7 @@ export declare const updateService: {
  * // same Counter: false
  * ```
  *
- * @category utils
+ * @category layers
  * @since 2.0.0
  */
 export declare const fresh: <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, R>;
@@ -3294,7 +3271,8 @@ export declare const fresh: <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, R>;
  *
  * **When to use**
  *
- * Use when your entire application is a layer, such as an HTTP server.
+ * Use when you model your entire application as a layer, such as an HTTP
+ * server.
  *
  * **Details**
  *
@@ -3663,7 +3641,7 @@ export declare const satisfiesServicesType: <RIn>() => <ROut, E, RIn2 extends RI
  * @see {@link span} for creating a layer span
  * @see {@link withSpan} for wrapping layer construction in a span
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface SpanOptions extends Tracer.SpanOptions {