@typed/fx 2.0.0-beta.3 → 2.0.0-beta.5

package/dist/Fx/Fx.js

@@ -2,31 +2,62 @@ import * as Effect from "effect/Effect";
 import { identity } from "effect/Function";
 import { effect } from "effect/Layer";
 import { pipeArguments } from "effect/Pipeable";
-import * as ServiceMap from "effect/ServiceMap";
-import { provideServices } from "./combinators/provide.js";
+import * as Context from "effect/Context";
+import { provideContext } from "./combinators/provide.js";
 import { FxTypeId, isFx } from "./TypeId.js";
 const VARIANCE = {
     _A: identity,
     _E: identity,
     _R: identity,
 };
+/**
+ * Defines an Effect service whose value is also a directly runnable `Fx`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Applications often need a producer selected by the Effect environment: a clock,
+ * event source, transport, or domain feed. `Service` keeps that dependency in `R`
+ * and provides the corresponding layer constructor without a parallel wrapper API.
+ *
+ * ## Ownership and lifetime
+ *
+ * Defining the class starts no work. `Class.make` acquires the producer when its layer
+ * is built, supplies the acquisition context to it, and binds its lifetime to the
+ * layer scope. Running the class reads the currently installed implementation.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Layer } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * class Ticks extends Fx.Service<Ticks, number>()("app/Ticks") {}
+ *
+ * const TicksLive = Ticks.make(Fx.succeed(1))
+ * const values = Fx.collectAll(Ticks).pipe(Effect.provide(TicksLive))
+ * const program = Effect.map(values, (items) => items[0])
+ * ```
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
 export function Service() {
     return (id) => {
-        const service = ServiceMap.Service(id);
+        const service = Context.Service(id);
         // eslint-disable-next-line @typescript-eslint/no-extraneous-class
         return class FxService {
             static id = id;
             static service = service;
             static make = (fx) => effect(service, Effect.gen(function* () {
-                const services = yield* Effect.services();
+                const services = yield* Effect.context();
                 const result = isFx(fx) ? fx : yield* fx;
-                return provideServices(result, services);
+                return provideContext(result, services);
             }));
             static [FxTypeId] = VARIANCE;
             static pipe = function () {
                 return pipeArguments(this, arguments);
             };
-            static run = (sink) => Effect.flatMap(service.asEffect(), (fx) => fx.run(sink));
+            static run = (sink) => Effect.flatMap(service, (fx) => fx.run(sink));
             constructor() {
                 return FxService;
             }

package/dist/Fx/TypeId.d.ts

@@ -1,18 +1,64 @@
 import type { Fx } from "./Fx.js";
 /**
- * The unique type identifier for Fx.
+ * Runtime symbol carried by every `Fx` implementation.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A global symbol lets independent packages recognize an `Fx` structurally without
+ * invoking it or relying on a concrete implementation class.
+ *
+ * ## Ownership and lifetime
+ *
+ * Reading or comparing the symbol starts no work and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { FxTypeId, succeed } from "@typed/fx/Fx"
+ *
+ * const carriesFxProtocol = FxTypeId in succeed("ready")
+ * ```
+ *
  * @since 1.0.0
  * @category symbol
  */
 export declare const FxTypeId: unique symbol;
 /**
- * The unique type identifier type for Fx.
+ * Type of the `FxTypeId` protocol symbol.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Implementations can declare the exact computed property required by `Fx`.
+ *
+ * ## Ownership and lifetime
+ *
+ * This alias performs no runtime work.
  * @since 1.0.0
  * @category symbol
  */
 export type FxTypeId = typeof FxTypeId;
 /**
- * Checks if a value is an Fx.
+ * Checks whether a value carries the `FxTypeId` protocol property.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Interoperability code can distinguish an already constructed `Fx` from effects,
+ * streams, iterables, and arbitrary values before choosing an explicit adapter.
+ *
+ * ## Ownership and lifetime
+ *
+ * The guard performs one property check. It does not subscribe to or run the value.
+ *
+ * @example
+ * ```ts
+ * import { isFx, succeed } from "@typed/fx/Fx"
+ *
+ * const candidate: unknown = succeed(42)
+ * const value = isFx(candidate) ? candidate : succeed(candidate)
+ * ```
+ *
  * @since 1.0.0
  * @category guards
  */

package/dist/Fx/TypeId.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TypeId.d.ts","sourceRoot":"","sources":["../../src/Fx/TypeId.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,QAAQ,eAA6B,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC;AAEvC;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAEvD"}
+{"version":3,"file":"TypeId.d.ts","sourceRoot":"","sources":["../../src/Fx/TypeId.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,QAAQ,eAA6B,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAEvD"}

package/dist/Fx/TypeId.js

@@ -1,12 +1,49 @@
 import { hasProperty } from "effect/Predicate";
 /**
- * The unique type identifier for Fx.
+ * Runtime symbol carried by every `Fx` implementation.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A global symbol lets independent packages recognize an `Fx` structurally without
+ * invoking it or relying on a concrete implementation class.
+ *
+ * ## Ownership and lifetime
+ *
+ * Reading or comparing the symbol starts no work and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { FxTypeId, succeed } from "@typed/fx/Fx"
+ *
+ * const carriesFxProtocol = FxTypeId in succeed("ready")
+ * ```
+ *
  * @since 1.0.0
  * @category symbol
  */
 export const FxTypeId = Symbol.for("@typed/fx/Fx");
 /**
- * Checks if a value is an Fx.
+ * Checks whether a value carries the `FxTypeId` protocol property.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Interoperability code can distinguish an already constructed `Fx` from effects,
+ * streams, iterables, and arbitrary values before choosing an explicit adapter.
+ *
+ * ## Ownership and lifetime
+ *
+ * The guard performs one property check. It does not subscribe to or run the value.
+ *
+ * @example
+ * ```ts
+ * import { isFx, succeed } from "@typed/fx/Fx"
+ *
+ * const candidate: unknown = succeed(42)
+ * const value = isFx(candidate) ? candidate : succeed(candidate)
+ * ```
+ *
  * @since 1.0.0
  * @category guards
  */

package/dist/Fx/combinators/additive.d.ts

@@ -6,8 +6,34 @@ import type { Fx } from "../Fx.js";
  * **Completion:** The merged stream completes when **both** input streams have
  * completed.
  *
- * **Errors:** The first failure from either stream fails the merged stream;
- * the other stream is interrupted.
+ * **Failures:** Every failure Cause is delivered to the downstream Sink. Delivery does not make
+ * `Fx.run` fail, so `merge` does not itself cancel the sibling; a terminal observer may choose to.
+ *
+ * @remarks
+ * ## Why
+ * `merge` preserves both producers instead of imposing a pairing relationship. Each input value is
+ * emitted once as soon as its source pushes it, so inter-source ordering is intentionally undefined.
+ *
+ * ## Ownership and lifetime
+ * Both runs are children of the consumer and completion waits for both. Downstream interruption
+ * cancels the remaining runs. A source Cause is only sent to `sink.onFailure`; whether that callback
+ * ends observation is Sink policy, not an intrinsic terminal rule of `merge`.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const deliveries = yield* Ref.make<Array<string>>([])
+ *   const sink = Sink.make(
+ *     () => Ref.update(deliveries, (xs) => [...xs, "failure"]),
+ *     (value: string) => Ref.update(deliveries, (xs) => [...xs, value])
+ *   )
+ *   yield* Fx.merge(Fx.fail("left failed"), Fx.succeed("right continued")).run(sink)
+ *   return yield* Ref.get(deliveries) // both "failure" and "right continued"
+ * })
+ * ```
  *
  * @param that - The second Fx stream.
  * @returns An Fx that emits values from both streams.
@@ -26,9 +52,35 @@ export declare const merge: {
  * **Completion:** The concatenated stream completes when the **second** stream
  * completes (the first must complete before the second starts).
  *
- * **Errors:** If the first stream fails, the concatenated stream fails and the
- * second is never run. If the second stream fails, the concatenated stream
- * fails after the first has already completed.
+ * **Failures:** A source Cause is delivered to the Sink. Because `Fx.run` is infallible, delivery
+ * alone does not suppress the continuation: the right source is run after the left run returns.
+ *
+ * @remarks
+ * ## Why
+ * `concat` makes subscription order explicit: the right source is not acquired until the left run
+ * returns. It preserves every value and each source's internal order. A failure callback can be
+ * followed by continuation values when the Sink handles the Cause without interrupting the run.
+ *
+ * ## Ownership and lifetime
+ * Only one source is active at a time. Interruption stops the active source and prevents later
+ * acquisition. Failure is Sink delivery rather than a failing `Fx.run` Effect, so it does not by
+ * itself prevent the right source from being acquired.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const deliveries = yield* Ref.make<Array<string>>([])
+ *   const sink = Sink.make(
+ *     () => Ref.update(deliveries, (xs) => [...xs, "failure"]),
+ *     (value: string) => Ref.update(deliveries, (xs) => [...xs, value])
+ *   )
+ *   yield* Fx.concat(Fx.fail("left failed"), Fx.succeed("right still runs")).run(sink)
+ *   return yield* Ref.get(deliveries) // ["failure", "right still runs"]
+ * })
+ * ```
  *
  * @param that - The second Fx stream (run after the first completes).
  * @returns An Fx that emits values from the first stream, then the second.
@@ -43,6 +95,34 @@ export declare const concat: {
  * Zips two Fx streams in strict lockstep and emits only the left value.
  * Completes when the **first** of the two streams completes.
  *
+ * @remarks
+ * ## Why
+ * `zipLeft` uses the right source as a one-for-one pacing or validation partner while retaining the
+ * left payload. It emits one left value per completed pair and preserves pair order.
+ *
+ * ## Ownership and lifetime
+ * Both sources run concurrently. The first run to complete ends pairing and interrupts the other,
+ * while consumer interruption stops both. A failure Cause is delivered to the Sink but does not by
+ * itself end pairing; a producer may continue and supply a value afterward.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const deliveries = yield* Ref.make<Array<string>>([])
+ *   const left = Fx.make<number, string>((sink) =>
+ *     sink.onFailure(Cause.fail("warning")).pipe(Effect.andThen(sink.onSuccess(1)))
+ *   )
+ *   yield* Fx.zipLeft(left, Fx.succeed("pair")).run(Sink.make(
+ *     () => Ref.update(deliveries, (xs) => [...xs, "failure"]),
+ *     (value) => Ref.update(deliveries, (xs) => [...xs, `value:${value}`])
+ *   ))
+ *   return yield* Ref.get(deliveries) // ["failure", "value:1"]
+ * })
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits values from the left stream only.
  * @since 1.0.0
@@ -56,6 +136,29 @@ export declare const zipLeft: {
  * Zips two Fx streams in strict lockstep and emits only the right value.
  * Completes when the **first** of the two streams completes.
  *
+ * @remarks
+ * ## Why
+ * `zipRight` pairs both sources but deliberately keeps the right payload. It emits once per pair,
+ * in pairing order, and never emits an unmatched right value.
+ *
+ * ## Ownership and lifetime
+ * Both runs belong to the consumer. The first completion or consumer interruption cancels the
+ * remaining run and releases the lockstep queues. Failure is Sink delivery, not an automatic stop;
+ * pairing can continue when the failing producer remains active and later emits a value.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const left = Fx.make<number, string>((sink) =>
+ *   sink.onFailure(Cause.fail("warning")).pipe(Effect.andThen(sink.onSuccess(1)))
+ * )
+ * const program = Fx.zipRight(left, Fx.succeed("paired")).run(
+ *   Sink.make(Effect.logError, Effect.log)
+ * ) // logs the failure and then "paired"
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits values from the right stream only.
  * @since 1.0.0
@@ -69,6 +172,30 @@ export declare const zipRight: {
  * Merges two Fx streams and emits only values from the left stream.
  * Both streams run concurrently; completion when **both** complete.
  *
+ * @remarks
+ * ## Why
+ * `mergeLeft` keeps the right producer's lifetime and failure signal while suppressing its values.
+ * Every left value is emitted once; right emissions only affect scheduling.
+ *
+ * ## Ownership and lifetime
+ * Both sources are acquired together and owned by the consuming run. Interruption cancels both and
+ * normal completion waits for both. A Cause from either source is delivered to the Sink but does not
+ * intrinsically cancel its sibling; right successes remain suppressed by the filter.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const failures = yield* Ref.make(0)
+ *   yield* Fx.mergeLeft(Fx.succeed("visible"), Fx.fail("hidden side failed")).run(
+ *     Sink.make(() => Ref.update(failures, (n) => n + 1), () => Effect.void)
+ *   )
+ *   return yield* Ref.get(failures) // 1; failure is still delivered
+ * })
+ * ```
+ *
  * @param that - The second Fx stream (values are dropped).
  * @returns An Fx that emits only values from the left stream.
  * @since 1.0.0
@@ -82,6 +209,30 @@ export declare const mergeLeft: {
  * Merges two Fx streams and emits only values from the right stream.
  * Both streams run concurrently; completion when **both** complete.
  *
+ * @remarks
+ * ## Why
+ * `mergeRight` observes the left producer's completion and failure while exposing only right
+ * values. Each right value is emitted once with no deterministic ordering against hidden left work.
+ *
+ * ## Ownership and lifetime
+ * The consumer owns both concurrent runs and normal completion waits for both. Interruption cancels
+ * both. A Cause is delivered to the Sink without inherently canceling the sibling; left successes
+ * remain suppressed even while their failures are observable.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const values = yield* Ref.make<Array<string>>([])
+ *   yield* Fx.mergeRight(Fx.fail("hidden side failed"), Fx.succeed("visible")).run(
+ *     Sink.make(() => Effect.void, (value) => Ref.update(values, (xs) => [...xs, value]))
+ *   )
+ *   return yield* Ref.get(values) // ["visible"]
+ * })
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits only values from the right stream.
  * @since 1.0.0

package/dist/Fx/combinators/additive.d.ts.map

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

package/dist/Fx/combinators/additive.js

@@ -11,8 +11,34 @@ import { zip } from "./zip.js";
  * **Completion:** The merged stream completes when **both** input streams have
  * completed.
  *
- * **Errors:** The first failure from either stream fails the merged stream;
- * the other stream is interrupted.
+ * **Failures:** Every failure Cause is delivered to the downstream Sink. Delivery does not make
+ * `Fx.run` fail, so `merge` does not itself cancel the sibling; a terminal observer may choose to.
+ *
+ * @remarks
+ * ## Why
+ * `merge` preserves both producers instead of imposing a pairing relationship. Each input value is
+ * emitted once as soon as its source pushes it, so inter-source ordering is intentionally undefined.
+ *
+ * ## Ownership and lifetime
+ * Both runs are children of the consumer and completion waits for both. Downstream interruption
+ * cancels the remaining runs. A source Cause is only sent to `sink.onFailure`; whether that callback
+ * ends observation is Sink policy, not an intrinsic terminal rule of `merge`.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const deliveries = yield* Ref.make<Array<string>>([])
+ *   const sink = Sink.make(
+ *     () => Ref.update(deliveries, (xs) => [...xs, "failure"]),
+ *     (value: string) => Ref.update(deliveries, (xs) => [...xs, value])
+ *   )
+ *   yield* Fx.merge(Fx.fail("left failed"), Fx.succeed("right continued")).run(sink)
+ *   return yield* Ref.get(deliveries) // both "failure" and "right continued"
+ * })
+ * ```
  *
  * @param that - The second Fx stream.
  * @returns An Fx that emits values from both streams.
@@ -28,9 +54,35 @@ export const merge = dual(2, (self, that) => mergeAll(self, that));
  * **Completion:** The concatenated stream completes when the **second** stream
  * completes (the first must complete before the second starts).
  *
- * **Errors:** If the first stream fails, the concatenated stream fails and the
- * second is never run. If the second stream fails, the concatenated stream
- * fails after the first has already completed.
+ * **Failures:** A source Cause is delivered to the Sink. Because `Fx.run` is infallible, delivery
+ * alone does not suppress the continuation: the right source is run after the left run returns.
+ *
+ * @remarks
+ * ## Why
+ * `concat` makes subscription order explicit: the right source is not acquired until the left run
+ * returns. It preserves every value and each source's internal order. A failure callback can be
+ * followed by continuation values when the Sink handles the Cause without interrupting the run.
+ *
+ * ## Ownership and lifetime
+ * Only one source is active at a time. Interruption stops the active source and prevents later
+ * acquisition. Failure is Sink delivery rather than a failing `Fx.run` Effect, so it does not by
+ * itself prevent the right source from being acquired.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const deliveries = yield* Ref.make<Array<string>>([])
+ *   const sink = Sink.make(
+ *     () => Ref.update(deliveries, (xs) => [...xs, "failure"]),
+ *     (value: string) => Ref.update(deliveries, (xs) => [...xs, value])
+ *   )
+ *   yield* Fx.concat(Fx.fail("left failed"), Fx.succeed("right still runs")).run(sink)
+ *   return yield* Ref.get(deliveries) // ["failure", "right still runs"]
+ * })
+ * ```
  *
  * @param that - The second Fx stream (run after the first completes).
  * @returns An Fx that emits values from the first stream, then the second.
@@ -42,6 +94,34 @@ export const concat = dual(2, (self, that) => continueWith(self, () => that));
  * Zips two Fx streams in strict lockstep and emits only the left value.
  * Completes when the **first** of the two streams completes.
  *
+ * @remarks
+ * ## Why
+ * `zipLeft` uses the right source as a one-for-one pacing or validation partner while retaining the
+ * left payload. It emits one left value per completed pair and preserves pair order.
+ *
+ * ## Ownership and lifetime
+ * Both sources run concurrently. The first run to complete ends pairing and interrupts the other,
+ * while consumer interruption stops both. A failure Cause is delivered to the Sink but does not by
+ * itself end pairing; a producer may continue and supply a value afterward.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const deliveries = yield* Ref.make<Array<string>>([])
+ *   const left = Fx.make<number, string>((sink) =>
+ *     sink.onFailure(Cause.fail("warning")).pipe(Effect.andThen(sink.onSuccess(1)))
+ *   )
+ *   yield* Fx.zipLeft(left, Fx.succeed("pair")).run(Sink.make(
+ *     () => Ref.update(deliveries, (xs) => [...xs, "failure"]),
+ *     (value) => Ref.update(deliveries, (xs) => [...xs, `value:${value}`])
+ *   ))
+ *   return yield* Ref.get(deliveries) // ["failure", "value:1"]
+ * })
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits values from the left stream only.
  * @since 1.0.0
@@ -52,6 +132,29 @@ export const zipLeft = dual(2, (self, that) => map(zip(self, that), (pair) => pa
  * Zips two Fx streams in strict lockstep and emits only the right value.
  * Completes when the **first** of the two streams completes.
  *
+ * @remarks
+ * ## Why
+ * `zipRight` pairs both sources but deliberately keeps the right payload. It emits once per pair,
+ * in pairing order, and never emits an unmatched right value.
+ *
+ * ## Ownership and lifetime
+ * Both runs belong to the consumer. The first completion or consumer interruption cancels the
+ * remaining run and releases the lockstep queues. Failure is Sink delivery, not an automatic stop;
+ * pairing can continue when the failing producer remains active and later emits a value.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const left = Fx.make<number, string>((sink) =>
+ *   sink.onFailure(Cause.fail("warning")).pipe(Effect.andThen(sink.onSuccess(1)))
+ * )
+ * const program = Fx.zipRight(left, Fx.succeed("paired")).run(
+ *   Sink.make(Effect.logError, Effect.log)
+ * ) // logs the failure and then "paired"
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits values from the right stream only.
  * @since 1.0.0
@@ -62,6 +165,30 @@ export const zipRight = dual(2, (self, that) => map(zip(self, that), (pair) => p
  * Merges two Fx streams and emits only values from the left stream.
  * Both streams run concurrently; completion when **both** complete.
  *
+ * @remarks
+ * ## Why
+ * `mergeLeft` keeps the right producer's lifetime and failure signal while suppressing its values.
+ * Every left value is emitted once; right emissions only affect scheduling.
+ *
+ * ## Ownership and lifetime
+ * Both sources are acquired together and owned by the consuming run. Interruption cancels both and
+ * normal completion waits for both. A Cause from either source is delivered to the Sink but does not
+ * intrinsically cancel its sibling; right successes remain suppressed by the filter.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const failures = yield* Ref.make(0)
+ *   yield* Fx.mergeLeft(Fx.succeed("visible"), Fx.fail("hidden side failed")).run(
+ *     Sink.make(() => Ref.update(failures, (n) => n + 1), () => Effect.void)
+ *   )
+ *   return yield* Ref.get(failures) // 1; failure is still delivered
+ * })
+ * ```
+ *
  * @param that - The second Fx stream (values are dropped).
  * @returns An Fx that emits only values from the left stream.
  * @since 1.0.0
@@ -78,6 +205,30 @@ export const mergeLeft = dual(2, (self, that) => {
  * Merges two Fx streams and emits only values from the right stream.
  * Both streams run concurrently; completion when **both** complete.
  *
+ * @remarks
+ * ## Why
+ * `mergeRight` observes the left producer's completion and failure while exposing only right
+ * values. Each right value is emitted once with no deterministic ordering against hidden left work.
+ *
+ * ## Ownership and lifetime
+ * The consumer owns both concurrent runs and normal completion waits for both. Interruption cancels
+ * both. A Cause is delivered to the Sink without inherently canceling the sibling; left successes
+ * remain suppressed even while their failures are observable.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const values = yield* Ref.make<Array<string>>([])
+ *   yield* Fx.mergeRight(Fx.fail("hidden side failed"), Fx.succeed("visible")).run(
+ *     Sink.make(() => Effect.void, (value) => Ref.update(values, (xs) => [...xs, value]))
+ *   )
+ *   return yield* Ref.get(values) // ["visible"]
+ * })
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits only values from the right stream.
  * @since 1.0.0