@typed/fx 2.0.0-beta.4 → 2.0.0-beta.6

package/dist/Subject/Subject.js

@@ -1,3 +1,5 @@
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
@@ -8,12 +10,50 @@ import * as Option from "effect/Option";
 import { pipeArguments } from "effect/Pipeable";
 import * as Scope from "effect/Scope";
 import * as Context from "effect/Context";
+import { fail } from "../Fx/constructors/fail.js";
 import { RingBuffer } from "../Fx/internal/ring-buffer.js";
 import { awaitScopeClose, withExtendedScope } from "../Fx/internal/scope.js";
 import { FxTypeId } from "../Fx/TypeId.js";
 /**
- * Shares the execution of an Fx among multiple subscribers using a Subject.
- * The source Fx is started when the first subscriber arrives and stopped when the last one leaves.
+ * Shares one active execution of an `Fx` among subscribers through the supplied `Subject`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Use `share` when the caller must choose the multicast boundary—for example, a replaying subject,
+ * a renderer-independent state object, or a service-backed subject—while ensuring that simultaneous
+ * consumers do not duplicate the source's effects.
+ *
+ * ## Subscription and publication
+ *
+ * A subscriber is registered with the subject before the source starts, so the first subscriber
+ * observes synchronous first values and failures. The first active subscriber starts the source;
+ * later subscribers join that execution. When the last subscriber leaves, the source fiber is
+ * interrupted. A later subscriber starts a fresh session.
+ *
+ * ## Errors, services, and interruption
+ *
+ * Source successes and failures are pushed unchanged through the subject. The returned `Fx`
+ * requires the union of source services and subject services.
+ *
+ * ## Ownership and lifetime
+ *
+ * `Scope` owns each individual subscription. The shared source is finalized exactly once when the
+ * active session ends or the source itself exits. `share` takes session ownership of the supplied
+ * subject: source exit calls its `interrupt`, closing all of that subject's subscribers and clearing
+ * retained state. Do not concurrently reuse the same subject for an independently owned producer
+ * or subscriber population.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * const backing = Subject.unsafeMake<number>(1)
+ * const request = Fx.fromEffect(Effect.succeed(42))
+ * const shared = Subject.share(request, backing)
+ * ```
  *
  * @param fx - The source Fx.
  * @param subject - The subject to use for multicasting.
@@ -38,21 +78,215 @@ const VARIANCE = {
     _E: identity,
     _R: identity,
 };
+const MAX_REPLAY_CAPACITY = 4294967295;
+const INVALID_REPLAY_CAPACITY_MESSAGE = "Replay capacity must be an integer from 0 through 4294967295";
+const isReplayCapacity = (capacity) => Number.isInteger(capacity) && capacity >= 0 && capacity <= MAX_REPLAY_CAPACITY;
+const invalidReplayCapacity = () => new Cause.IllegalArgumentError(INVALID_REPLAY_CAPACITY_MESSAGE);
+/**
+ * The concrete lazy `Fx` returned by `share`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `Share` exposes the ref-counted sharing mechanism as an ordinary `Fx`: one source execution feeds
+ * the selected subject while each caller has an independently scoped subscription to that subject.
+ * Most callers should prefer `share`, `multicast`, `hold`, or `replay` for clearer intent.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction acquires nothing. The first executing `run` starts a detached source fiber; the
+ * final executing `run` interrupts it. Source completion interrupts the subject's current
+ * subscribers. Source, subject, and sink services are required only when `run` executes.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Share, unsafeMake } from "@typed/fx/Subject"
+ *
+ * const shared = new Share(Fx.succeed(1), unsafeMake<number>())
+ * ```
+ *
+ * @since 1.0.0
+ * @category models
+ */
 export class Share {
+    /**
+     * Carries `Fx` variance information for the shared output, error, and service channels.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Lets generic `Fx` utilities recognize and infer a `Share` without inspecting its runtime fields.
+     *
+     * ## Ownership and lifetime
+     *
+     * The marker is immutable metadata and acquires no resources.
+     *
+     * @since 1.0.0
+     * @category type-level
+     */
     [FxTypeId] = VARIANCE;
+    /**
+     * Tracks the source fiber for the current active subscriber session.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Gives the final departing subscriber an exact fiber to interrupt without restarting or
+     * duplicating the source.
+     *
+     * ## Ownership and lifetime
+     *
+     * The reference is empty before a session, set after the first subscriber starts the source, and
+     * cleared before or when that session ends. It does not outlive the `Share` instance.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     _FxFiber = MutableRef.make(Option.none());
+    /**
+     * Tracks how many executing `run` effects participate in the active source session.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Implements the first-subscriber start and last-subscriber stop boundary.
+     *
+     * ## Ownership and lifetime
+     *
+     * The counter is owned by the `Share` instance and never falls below zero. Each executing `run`
+     * increments once and decrements in its exit finalizer.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     _RefCount = new RefCounter();
+    /**
+     * The source whose execution is shared.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Retains the original source so every active session can start exactly that `Fx`.
+     *
+     * ## Ownership and lifetime
+     *
+     * Holding the `Fx` value starts no work. Its `R` services and cleanup participate only while a
+     * subscriber session is active.
+     *
+     * @since 1.0.0
+     * @category inputs
+     */
     i0;
+    /**
+     * The multicast subject receiving source publications.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Separates source sharing from retention and publication policy.
+     *
+     * ## Ownership and lifetime
+     *
+     * `Share` does not allocate this subject. It subscribes sinks to it and interrupts it when the
+     * source session exits; the subject's `R2` services remain required by `run`.
+     *
+     * @since 1.0.0
+     * @category inputs
+     */
     i1;
+    /**
+     * Creates the lazy shared `Fx`; source acquisition waits until the first call to `run` executes.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Keeps selection of the source and multicast policy separate from their execution.
+     *
+     * ## Ownership and lifetime
+     *
+     * The constructor only stores `i0` and `i1`; it starts no fiber and installs no finalizer.
+     *
+     * @example
+     * ```ts
+     * import { Fx } from "@typed/fx"
+     * import { Share, unsafeMake } from "@typed/fx/Subject"
+     *
+     * const shared = new Share(Fx.succeed("ready"), unsafeMake<string>())
+     * ```
+     *
+     * @since 1.0.0
+     * @category constructors
+     */
     constructor(i0, i1) {
         this.i0 = i0;
         this.i1 = i1;
     }
+    /**
+     * Returns this value through the concrete class's zero-argument pipe entrypoint.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Supplies the runtime pipe hook required by `Fx`; the concrete `Share` declaration currently
+     * publishes only its zero-argument signature, so typed combinator composition should target the
+     * `Fx` returned by `share`, `multicast`, `hold`, or `replay`.
+     *
+     * ## Ownership and lifetime
+     *
+     * Calling `pipe` itself acquires no resources; only an executing downstream `run` starts work.
+     *
+     * @example
+     * ```ts
+     * import { Fx } from "@typed/fx"
+     * import { Share, unsafeMake } from "@typed/fx/Subject"
+     *
+     * const shared = new Share(Fx.succeed(1), unsafeMake<number>())
+     * const same = shared.pipe()
+     * ```
+     *
+     * @since 1.0.0
+     * @category utilities
+     */
     pipe() {
         return pipeArguments(this, arguments);
     }
+    /**
+     * Registers `sink`, joins or starts the active source session, and remains active until the
+     * subscription ends. Interruption removes this subscriber and stops the source if it was last.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Implements `Fx` consumption while coordinating one source execution across independent sinks.
+     *
+     * ## Ownership and lifetime
+     *
+     * The caller's `Scope` owns its subject subscription. Source `R`, subject `R2`, and sink `R3`
+     * services are required during execution. Source failures are published to the sink rather than
+     * failing this returned Effect, whose error channel is `never`.
+     *
+     * @example
+     * ```ts
+     * import { Effect } from "effect"
+     * import { Fx } from "@typed/fx"
+     * import * as Sink from "@typed/fx/Sink"
+     * import { Share, unsafeMake } from "@typed/fx/Subject"
+     *
+     * const shared = new Share(Fx.succeed(1), unsafeMake<number>())
+     * const run = shared.run(
+     *   Sink.make(
+     *     () => Effect.void,
+     *     (value) => Effect.sync(() => console.log(value))
+     *   )
+     * )
+     * ```
+     *
+     * @since 1.0.0
+     * @category runners
+     */
     run(sink) {
-        return Effect.flatMap(this.initialize(), () => Effect.onExit(this.i1.run(sink), () => this._RefCount.decrement() === 0 ? this.interrupt() : Effect.void));
+        return Effect.onExit(Effect.acquireUseRelease(Effect.forkScoped(this.i1.run(sink), { startImmediately: true }), (fiber) => Effect.andThen(this.initialize(), Fiber.join(fiber)), Fiber.interrupt), () => (this._RefCount.decrement() === 0 ? this.interrupt() : Effect.void));
     }
     initialize() {
         return Effect.suspend(() => {
@@ -75,8 +309,27 @@ export class Share {
     }
 }
 /**
- * Multicasts an Fx to multiple subscribers.
- * The source Fx is shared, so side effects only happen once per active session (ref count > 0).
+ * Multicasts an `Fx` without replaying values that arrived before a subscriber joined.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `multicast` is the zero-retention sharing policy: simultaneous subscribers share source work,
+ * while consumers that arrive later receive only later publications.
+ *
+ * ## Ownership and lifetime
+ *
+ * The first subscriber starts one source execution and the last subscriber interrupts it. A later
+ * subscriber starts a fresh execution. No replay buffer is retained. Source errors and services
+ * are preserved, and `Scope` owns each subscription.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * const sharedTicks = Subject.multicast(Fx.periodic("1 second"))
+ * ```
  *
  * @param fx - The source Fx.
  * @returns A multicasted `Fx`.
@@ -87,7 +340,34 @@ export function multicast(fx) {
     return new Share(fx, unsafeMake(0));
 }
 /**
- * Holds the latest value emitted by the Fx and replays it to new subscribers.
+ * Shares an `Fx` and immediately replays its latest success or failure to each new subscriber.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `hold` gives late subscribers the current publication without restarting an already active
+ * source, making it suitable for current-value streams and state-like projections.
+ *
+ * ## Ownership and lifetime
+ *
+ * One retained `Exit` belongs to the active shared subject. The first subscriber starts the source,
+ * the last subscriber interrupts it, and interruption clears the retained exit. Source errors and
+ * services remain visible in the returned `Fx`; subscription cleanup belongs to `Scope`.
+ *
+ * ## Join-during-publication behavior
+ *
+ * The latest `Exit` is retained before it enters the serialized publication queue. If a subscriber
+ * joins while an earlier publication is still draining, it can receive that queued exit immediately
+ * as replay and then receive it again when the queue reaches it. Consumers that require exactly-once
+ * delivery across concurrent subscription and publication must coordinate that boundary externally.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * const currentStatus = Subject.hold(Fx.succeed("ready"))
+ * ```
  *
  * @param fx - The source Fx.
  * @returns A shared `Fx` that replays the latest value.
@@ -98,41 +378,226 @@ export function hold(fx) {
     return new Share(fx, unsafeMake(1));
 }
 /**
- * Replays the last `capacity` values emitted by the Fx to new subscribers.
+ * Shares an `Fx` and replays up to the last `capacity` successes or failures to new subscribers.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `replay` makes retention an explicit caller-selected policy rather than an implicit property of
+ * every shared stream. Capacity `0` is equivalent to multicast retention; capacity `1` has hold
+ * semantics; larger values replay the retained window from oldest to newest.
+ *
+ * ## Errors and interruption
+ *
+ * A non-integer, negative, or larger-than-32-bit capacity produces an `Fx` that fails with
+ * `Cause.IllegalArgumentError` without starting the source. Valid buffers retain `Exit` values, so
+ * typed failures keep their original causes and order. The last subscriber interrupts the source
+ * and clears the buffer; source services remain in the return type.
+ *
+ * ## Ownership and lifetime
+ *
+ * `Scope` owns each subscription and the final subscriber owns shutdown of the active source
+ * session. Buffer memory belongs to that session and is cleared when it is interrupted.
  *
- * @param capacity - The number of values to buffer and replay.
+ * ## Join-during-publication behavior
+ *
+ * Each `Exit` enters the replay buffer before it enters the serialized publication queue. A
+ * subscriber joining while an earlier publication is still draining can replay a later queued exit
+ * and then receive the same exit again when normal delivery reaches it. Replay guarantees retained
+ * order, not exactly-once delivery across a concurrent subscribe/publish race.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * const recent = Fx.fromIterable([1, 2, 3]).pipe(Subject.replay(2))
+ * ```
+ *
+ * @param capacity - An integer from 0 through 4,294,967,295. The buffer can retain up to
+ * `capacity` values, so callers own the memory policy for valid capacities. Invalid capacities
+ * fail through the Fx error channel with `Cause.IllegalArgumentError`.
  * @param fx - The source Fx.
  * @returns A shared `Fx` that replays values.
  * @since 1.0.0
  * @category combinators
  */
 export const replay = dual(2, function replay(fx, capacity) {
+    if (!isReplayCapacity(capacity)) {
+        return fail(invalidReplayCapacity());
+    }
     return new Share(fx, unsafeMake(capacity));
 });
 const DISCARD = { discard: true };
 /**
+ * Implements a zero-replay subject with scoped subscribers and serialized publication delivery.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This is the queueing core behind public subjects. It snapshots subscribers per publication and
+ * drains successes and failures in FIFO order without recursive stack growth.
+ *
+ * ## Publication and errors
+ *
+ * A non-reentrant publisher waits for its publication to finish delivery. A publisher called from
+ * the active drain fiber enqueues and returns immediately so subscriber callbacks cannot deadlock;
+ * the outer drain subsequently delivers that publication. Sink callback defects or interruption
+ * are handled by the sink boundary and do not become a typed Subject failure.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each `run` call creates a child scope for its sink and removes it on closure. `interrupt` closes
+ * all current child scopes. The instance may accept later subscriptions and publications.
+ *
+ * This class remains marked `@internal` and is not a supported construction API even though the
+ * current wildcard package export makes it import-reachable. Use `make` or `unsafeMake`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * const supported = Effect.scoped(Subject.make<number>())
+ * ```
+ *
+ * @since 1.0.0
+ * @category internal
  * @internal
  */
 export class SubjectImpl {
+    /**
+     * Carries the `Fx` variance channels implemented by this subject.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Allows the implementation to satisfy the runtime `Fx` protocol.
+     *
+     * ## Ownership and lifetime
+     *
+     * Immutable metadata; it acquires no resources.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     [FxTypeId] = VARIANCE;
     sinks = new Set();
+    publications = [];
+    publicationIndex = 0;
+    activePublication;
+    activeDrainFiberId = null;
+    /**
+     * Creates an empty zero-replay subject and binds its producer callbacks.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Initializes the internal queueing boundary without starting work.
+     *
+     * ## Ownership and lifetime
+     *
+     * Construction acquires no fibers or scopes; later `run` calls own subscriptions.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     constructor() {
         this.onFailure = this.onFailure.bind(this);
         this.onSuccess = this.onSuccess.bind(this);
     }
+    /**
+     * Delegates to the Effect pipeable protocol.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Lets the implementation participate in ordinary `Fx` composition.
+     *
+     * ## Ownership and lifetime
+     *
+     * Piping starts no subscription; execution begins only when the resulting `Fx` is run.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     pipe() {
         return pipeArguments(this, arguments);
     }
+    /**
+     * Registers a sink until its child scope closes.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Implements the subscription side of the `Fx` contract.
+     *
+     * ## Ownership and lifetime
+     *
+     * The caller's `Scope` owns this subscription and its captured `R2` context. Publications deliver
+     * `A` or `Cause<E>` to the sink; the returned Effect itself cannot fail.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     run(sink) {
         return this.addSink(sink, awaitScopeClose);
     }
+    /**
+     * Enqueues a failure publication for the current subscriber snapshot.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Preserves the complete Effect `Cause`, including defects and interruption, at the Sink boundary.
+     *
+     * ## Ownership and lifetime
+     *
+     * Non-reentrant callers wait for delivery; a call from the active drain fiber returns after
+     * enqueueing. The publication is not retained for later subscribers.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     onFailure(cause) {
         return this.onCause(cause);
     }
+    /**
+     * Enqueues a successful value for the current subscriber snapshot.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Provides the producer-facing push operation while preserving FIFO delivery.
+     *
+     * ## Ownership and lifetime
+     *
+     * Non-reentrant callers wait for delivery; a call from the active drain fiber returns after
+     * enqueueing. The value is not retained for later subscribers.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     onSuccess(a) {
         return this.onEvent(a);
     }
     interruptScopes = Effect.withFiber((fiber) => Effect.forEach(Array.from(this.sinks), ([, , scope]) => Scope.close(scope, Exit.interrupt(fiber.id)), DISCARD));
+    /**
+     * Closes every currently registered subscriber scope.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Gives the owner one cleanup boundary for all active subscriptions.
+     *
+     * ## Ownership and lifetime
+     *
+     * Finalizers run for current subscribers; later subscriptions remain possible. This base class
+     * retains no replay state.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     interrupt = this.interruptScopes;
     addSink(sink, f) {
         return withExtendedScope((innerScope) => Effect.contextWith((ctx) => {
@@ -142,28 +607,86 @@ export class SubjectImpl {
             return Effect.flatMap(Scope.addFinalizer(innerScope, remove), () => f(innerScope));
         }), "sequential");
     }
+    /**
+     * Samples the number of currently registered sinks without subscribing.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Exposes current demand for diagnostics and coordination.
+     *
+     * ## Ownership and lifetime
+     *
+     * The Effect reads the owned sink set when executed and retains no additional state.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     subscriberCount = Effect.sync(() => this.sinks.size);
     onEvent(a) {
-        if (this.sinks.size === 0)
-            return Effect.void;
-        else if (this.sinks.size === 1) {
-            const [sink, ctx] = this.sinks.values().next().value;
-            return runSinkEvent(sink, ctx, a);
-        }
-        else {
-            return Effect.forEach(this.sinks, ([sink, ctx]) => runSinkEvent(sink, ctx, a), DISCARD);
-        }
+        return this.enqueue(Exit.succeed(a));
     }
     onCause(cause) {
-        if (this.sinks.size === 0)
-            return Effect.void;
-        else if (this.sinks.size === 1) {
-            const [sink, ctx, scope] = this.sinks.values().next().value;
-            return runSinkCause(sink, ctx, scope, cause);
-        }
-        else {
-            return Effect.forEach(this.sinks, ([sink, ctx, scope]) => runSinkCause(sink, ctx, scope, cause), DISCARD);
-        }
+        return this.enqueue(Exit.failCause(cause));
+    }
+    enqueue(exit) {
+        return Effect.withFiber((fiber) => Effect.suspend(() => {
+            const publication = {
+                exit,
+                acknowledgement: Deferred.makeUnsafe(),
+            };
+            this.publications.push(publication);
+            if (this.activeDrainFiberId === fiber.id) {
+                return Effect.void;
+            }
+            else if (this.activeDrainFiberId !== null) {
+                return Deferred.await(publication.acknowledgement);
+            }
+            const ownerFiberId = fiber.id;
+            this.activeDrainFiberId = ownerFiberId;
+            return Effect.onExit(this.drain(ownerFiberId), (exit) => this.clearDrain(ownerFiberId, exit));
+        }));
+    }
+    drain(ownerFiberId) {
+        return Effect.suspend(() => {
+            const publication = this.publications[this.publicationIndex++];
+            if (publication === undefined) {
+                this.publications.length = 0;
+                this.publicationIndex = 0;
+                if (this.activeDrainFiberId === ownerFiberId) {
+                    this.activeDrainFiberId = null;
+                }
+                return Effect.void;
+            }
+            this.activePublication = publication;
+            const sinks = Array.from(this.sinks);
+            const deliver = Exit.match(publication.exit, {
+                onFailure: (cause) => Effect.forEach(sinks, ([sink, ctx, scope]) => runSinkCause(sink, ctx, scope, cause), DISCARD),
+                onSuccess: (value) => Effect.forEach(sinks, ([sink, ctx]) => runSinkEvent(sink, ctx, value), DISCARD),
+            });
+            return Effect.andThen(deliver, Effect.sync(() => {
+                Deferred.doneUnsafe(publication.acknowledgement, Effect.void);
+                this.activePublication = undefined;
+            }).pipe(Effect.andThen(() => this.drain(ownerFiberId))));
+        });
+    }
+    clearDrain(ownerFiberId, exit) {
+        return Effect.sync(() => {
+            if (Exit.isSuccess(exit) || this.activeDrainFiberId !== ownerFiberId) {
+                return;
+            }
+            const completion = Exit.asVoid(exit);
+            if (this.activePublication !== undefined) {
+                Deferred.doneUnsafe(this.activePublication.acknowledgement, completion);
+            }
+            for (let i = this.publicationIndex; i < this.publications.length; i++) {
+                Deferred.doneUnsafe(this.publications[i].acknowledgement, completion);
+            }
+            this.publications.length = 0;
+            this.publicationIndex = 0;
+            this.activePublication = undefined;
+            this.activeDrainFiberId = null;
+        });
     }
 }
 function runSinkEvent(sink, ctx, a) {
@@ -173,15 +696,92 @@ function runSinkCause(sink, ctx, scope, cause) {
     return Effect.provide(Effect.catchCause(sink.onFailure(cause), (error) => Scope.close(scope, Exit.failCause(error))), ctx);
 }
 /**
+ * Internal one-exit replay implementation used for public hold semantics.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Extends the serialized Subject core with a current `Exit`, allowing a new subscriber to observe
+ * the latest success or failure immediately.
+ *
+ * ## Join-during-publication behavior
+ *
+ * The current exit is updated before queue delivery. A subscriber joining while another
+ * publication drains can replay a later queued exit and receive it again when the queue reaches it.
+ *
+ * ## Ownership and lifetime
+ *
+ * The instance owns one retained exit. `interrupt` closes subscribers and clears it. This class is
+ * import-reachable under the current wildcard export but remains `@internal`; use `hold`, `make(1)`,
+ * or `unsafeMake(1)`.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * const supported = Subject.hold(Fx.succeed("ready"))
+ * ```
+ *
+ * @since 1.0.0
+ * @category internal
  * @internal
  */
 export class HoldSubjectImpl extends SubjectImpl {
+    /**
+     * Stores the most recently published success or failure.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Supplies the immediate current-state replay used when a sink subscribes.
+     *
+     * ## Ownership and lifetime
+     *
+     * Updated before enqueueing each publication and cleared by `interrupt`; it retains at most one
+     * `Exit<A, E>`.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     lastValue = MutableRef.make(Option.none());
+    /**
+     * Retains a success, then enqueues it for serialized delivery.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Makes the latest value immediately visible to subscribers without bypassing FIFO live delivery.
+     *
+     * ## Ownership and lifetime
+     *
+     * The retained value remains until replaced or interrupted. A reentrant call returns after
+     * enqueueing; a joining subscriber can therefore observe the queued value twice.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     onSuccess = (a) => Effect.suspend(() => {
         // Keep track of the last value emitted by the subject
         MutableRef.set(this.lastValue, Option.some(Exit.succeed(a)));
         return this.onEvent(a);
     });
+    /**
+     * Retains a failure cause, then enqueues it for serialized delivery.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Gives late subscribers the same current failure, preserving its complete `Cause`.
+     *
+     * ## Ownership and lifetime
+     *
+     * The retained failure remains until replaced or interrupted. A joining subscriber can replay a
+     * queued cause and receive it again from the live drain.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     onFailure = (cause) => {
         return Effect.suspend(() => {
             // Keep track of the last value emitted by the subject
@@ -189,6 +789,23 @@ export class HoldSubjectImpl extends SubjectImpl {
             return this.onCause(cause);
         });
     };
+    /**
+     * Registers a sink, delivers the retained exit if present, then awaits scope closure.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Combines a current-state read with the live Subject subscription.
+     *
+     * ## Ownership and lifetime
+     *
+     * The caller's `Scope` owns registration and captured `R2` services. Replay occurs before waiting
+     * for later publications; concurrent queued publication can duplicate that replay as described on
+     * the class.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     run(sink) {
         return this.addSink(sink, (scope) => Option.match(MutableRef.get(this.lastValue), {
             onNone: () => awaitScopeClose(scope),
@@ -196,38 +813,210 @@ export class HoldSubjectImpl extends SubjectImpl {
             onSome: (exit) => Effect.flatMap(Exit.match(exit, sink), () => awaitScopeClose(scope)),
         }));
     }
+    /**
+     * Closes current subscribers and clears the retained exit.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Couples subscription cleanup with current-state cleanup.
+     *
+     * ## Ownership and lifetime
+     *
+     * Later subscriptions remain possible but have no replay until another publication arrives.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     interrupt = Effect.tap(this.interruptScopes, Effect.sync(() => MutableRef.set(this.lastValue, Option.none())));
 }
 /**
+ * Internal bounded replay implementation used for public replay semantics.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Extends the serialized Subject core with an explicit-capacity FIFO window of successful and
+ * failed publications.
+ *
+ * ## Join-during-publication behavior
+ *
+ * Each exit enters the ring buffer before queue delivery. A subscriber joining while another
+ * publication drains can replay a later queued exit and receive it again when the queue reaches it.
+ *
+ * ## Ownership and lifetime
+ *
+ * The instance owns the supplied ring buffer. `interrupt` closes subscribers and clears the buffer.
+ * This class is import-reachable under the current wildcard export but remains `@internal`; use
+ * `replay`, `make`, or `unsafeMake`.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * const supported = Fx.fromIterable([1, 2, 3]).pipe(Subject.replay(2))
+ * ```
+ *
+ * @since 1.0.0
+ * @category internal
  * @internal
  */
 export class ReplaySubjectImpl extends SubjectImpl {
+    /**
+     * Stores the bounded FIFO window of retained successes and failures.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Makes replay capacity and eviction explicit in the implementation.
+     *
+     * ## Ownership and lifetime
+     *
+     * Owned by this subject, filled before live queue delivery, and emptied by `interrupt`.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     buffer;
+    /**
+     * Creates a replay subject around an already allocated ring buffer.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Keeps capacity validation and allocation in the public factories while this class owns replay.
+     *
+     * ## Ownership and lifetime
+     *
+     * Construction starts no fibers. The instance retains and later clears the supplied buffer.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     constructor(buffer) {
         super();
         this.buffer = buffer;
     }
+    /**
+     * Appends a success to the ring buffer, then enqueues it for live delivery.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Preserves one order for retained and live values while bounding memory by capacity.
+     *
+     * ## Ownership and lifetime
+     *
+     * The buffer evicts its oldest exit when full. A joining subscriber can replay this queued value
+     * and receive it again from the live drain.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     onSuccess = (a) => Effect.suspend(() => {
         // Keep track of the last value emitted by the subject
         this.buffer.push(Exit.succeed(a));
         return this.onEvent(a);
     });
+    /**
+     * Appends a failure cause to the ring buffer, then enqueues it for live delivery.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Replays failures in causal order without reducing them to typed error values.
+     *
+     * ## Ownership and lifetime
+     *
+     * The complete `Cause` remains retained until eviction or interruption. A joining subscriber can
+     * replay the queued cause and receive it again from the live drain.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     onFailure = (cause) => Effect.suspend(() => {
         this.buffer.push(Exit.failCause(cause));
         return this.onCause(cause);
     });
+    /**
+     * Registers a sink, replays the retained window oldest-to-newest, then awaits scope closure.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Gives late subscribers bounded history before they consume subsequent live publications.
+     *
+     * ## Ownership and lifetime
+     *
+     * The caller's `Scope` owns registration and captured `R2` services. Replay itself does not remove
+     * entries. Concurrent queued publication can duplicate an exit as described on the class.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     run(sink) {
         return this.addSink(sink, (scope) => Effect.flatMap(this.buffer.forEach(Exit.match(sink)), () => awaitScopeClose(scope)));
     }
+    /**
+     * Closes current subscribers and empties the replay buffer.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Releases both subscriber lifetimes and caller-selected retained memory at one boundary.
+     *
+     * ## Ownership and lifetime
+     *
+     * Later subscriptions remain possible but have no history until new publications arrive.
+     *
+     * @since 1.0.0
+     * @category internal
+     */
     interrupt = Effect.tap(this.interruptScopes, Effect.sync(() => this.buffer.clear()));
 }
 /**
- * Creates a `Subject` that replays the last `replay` values. You will need to manually call `interrupt` on the subject to clear resources.
- * @param replay - The number of values to replay.
+ * Immediately allocates a `Subject` with the requested replay capacity and manual ownership.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `unsafeMake` is the escape hatch for owners that cannot acquire through an Effect `Scope`, such
+ * as a long-lived host object with its own explicit teardown. Prefer `make` inside Effect programs.
+ *
+ * ## Ownership and lifetime
+ *
+ * Allocation is synchronous and starts no fibers. The caller must execute `interrupt` to close
+ * subscribers and clear retained `Exit` values. Capacity `0` retains nothing, capacity `1` retains
+ * the latest publication, and larger capacities retain the newest window in FIFO replay order.
+ *
+ * ## Errors
+ *
+ * Invalid capacities throw `Cause.IllegalArgumentError` synchronously; this function has no typed
+ * Effect error channel. Publishing and subscribing use the `E` and service channels of the returned
+ * subject.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * const events = Subject.unsafeMake<string>(10)
+ *
+ * const shutdown = events.interrupt
+ * const publish = events.onSuccess("ready").pipe(Effect.asVoid)
+ * ```
+ *
+ * @param replay - An integer from 0 through 4,294,967,295. The buffer can retain up to
+ * `replay` values, so callers own the memory policy for valid capacities.
  * @returns A `Subject` that replays the last `replay` values.
+ * @since 1.0.0
+ * @category constructors
  */
 export function unsafeMake(replay = 0) {
-    replay = Math.max(0, replay);
+    if (!isReplayCapacity(replay)) {
+        throw invalidReplayCapacity();
+    }
     if (replay === 0) {
         return new SubjectImpl();
     }
@@ -239,11 +1028,82 @@ export function unsafeMake(replay = 0) {
     }
 }
 /**
- * Create a Subject which utilizes a Scope to manage the lifecycle of the subject's resources.
+ * Acquires a `Subject` whose subscribers and replay state are released with the current `Scope`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `make` places the imperative subject boundary under Effect's structured resource ownership, so
+ * cancellation and scope closure cannot leave subscriptions or retained values behind.
+ *
+ * ## Ownership and lifetime
+ *
+ * The effect allocates when executed, not when described. Its required `Scope` installs a finalizer
+ * that runs `interrupt`, closing all subscriber scopes and clearing the replay buffer. Individual
+ * subscriber scopes may still end earlier without affecting other subscribers.
+ *
+ * ## Errors
+ *
+ * Invalid capacities fail in the typed error channel with `Cause.IllegalArgumentError`; no subject
+ * is allocated. Once acquired, publication callbacks cannot fail and the subject's `E` parameter
+ * describes failures that producers may publish to sinks.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * const program = Effect.gen(function* () {
+ *   const messages = yield* Subject.make<string>(1)
+ *   yield* messages.onSuccess("online")
+ *   return yield* messages.subscriberCount
+ * }).pipe(Effect.scoped)
+ * ```
+ *
+ * @since 1.0.0
+ * @category constructors
  */
 export function make(replay) {
-    return Effect.acquireRelease(Effect.sync(() => unsafeMake(replay)), (subject) => subject.interrupt);
+    const capacity = replay ?? 0;
+    if (!isReplayCapacity(capacity)) {
+        return Effect.fail(invalidReplayCapacity());
+    }
+    return Effect.acquireRelease(Effect.sync(() => unsafeMake(capacity)), (subject) => subject.interrupt);
 }
+/**
+ * Defines an Effect context service that is simultaneously a `Subject`, `Fx`, and `Sink` facade.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A named subject often represents an application-wide event boundary. `Service` keeps that
+ * boundary type-safe and lets producers, consumers, and layers compose through Effect's normal
+ * service channel instead of a module-global mutable instance.
+ *
+ * ## Ownership and lifetime
+ *
+ * Defining the class acquires nothing. Calling its static `make` creates a layer backed by scoped
+ * `Subject.make`; releasing the layer interrupts subscriptions and clears replay. Static `Fx` and
+ * `Sink` operations require `Self`, then delegate to the installed subject. Invalid replay
+ * capacities fail layer construction with `Cause.IllegalArgumentError`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ * import * as Subject from "@typed/fx/Subject"
+ *
+ * class Notifications extends Subject.Service<Notifications, string>()("Notifications") {}
+ *
+ * const program = Effect.gen(function* () {
+ *   yield* Notifications.onSuccess("saved")
+ *   return yield* Fx.first(Notifications)
+ * }).pipe(Effect.provide(Notifications.make(1)), Effect.scoped)
+ * ```
+ *
+ * @since 1.0.0
+ * @category context
+ */
 export function Service() {
     return (id) => {
         const service = Context.Service(id);
@@ -251,19 +1111,24 @@ export function Service() {
         return class SubjectService {
             static id = id;
             static service = service;
+            static {
+                // @effect-diagnostics-next-line floatingEffect:off
+                Object.assign(this, service);
+                Object.assign(this.prototype, Object.getPrototypeOf(service));
+            }
             static make = (replay) => Layer.effect(service, make(replay));
             static [FxTypeId] = VARIANCE;
             static pipe = function () {
                 return pipeArguments(this, arguments);
             };
             // Fx
-            static run = (sink) => Effect.flatMap(service.asEffect(), (subject) => subject.run(sink));
+            static run = (sink) => Effect.flatMap(service, (subject) => subject.run(sink));
             // Sink
-            static onSuccess = (value) => Effect.flatMap(service.asEffect(), (subject) => subject.onSuccess(value));
-            static onFailure = (cause) => Effect.flatMap(service.asEffect(), (subject) => subject.onFailure(cause));
+            static onSuccess = (value) => Effect.flatMap(service, (subject) => subject.onSuccess(value));
+            static onFailure = (cause) => Effect.flatMap(service, (subject) => subject.onFailure(cause));
             // Subject
-            static subscriberCount = Effect.flatMap(service.asEffect(), (subject) => subject.subscriberCount);
-            static interrupt = Effect.flatMap(service.asEffect(), (subject) => subject.interrupt);
+            static subscriberCount = Effect.flatMap(service, (subject) => subject.subscriberCount);
+            static interrupt = Effect.flatMap(service, (subject) => subject.interrupt);
             constructor() {
                 return SubjectService;
             }