@typed/fx 2.0.0-beta.0 → 2.0.0-beta.10

package/dist/RefSubject/RefSubject.js

@@ -2,6 +2,8 @@
 /** @effect-diagnostics missingEffectContext:skip-file */
 import * as Array from "effect/Array";
 import * as Effect from "effect/Effect";
+import * as Effectable from "effect/Effectable";
+import * as Semaphore from "effect/Semaphore";
 import { equals } from "effect/Equal";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
@@ -12,17 +14,18 @@ import { sum } from "effect/Number";
 import * as Option from "effect/Option";
 import { pipeArguments } from "effect/Pipeable";
 import * as Scope from "effect/Scope";
-import * as ServiceMap from "effect/ServiceMap";
+import * as Context from "effect/Context";
 import * as Stream from "effect/Stream";
 import { compact as fxCompact } from "../Fx/combinators/compact.js";
 import { continueWith } from "../Fx/combinators/continueWith.js";
 import { filterMapEffect as fxFilterMapEffect } from "../Fx/combinators/filterMapEffect.js";
 import { mapEffect as fxMapEffect } from "../Fx/combinators/mapEffect.js";
+import { mergeAll as fxMergeAll } from "../Fx/combinators/mergeAll.js";
+import { scanEffect as fxScanEffect } from "../Fx/combinators/scan.js";
 import { skipRepeats } from "../Fx/combinators/skipRepeats.js";
 import { slice as fxSlice } from "../Fx/combinators/slice.js";
 import { unwrap } from "../Fx/combinators/unwrap.js";
 import { fromEffect as fxFromEffect } from "../Fx/constructors/fromEffect.js";
-import { fromYieldable } from "../Fx/constructors/fromYieldable.js";
 import * as DeferredRef from "../Fx/internal/DeferredRef.js";
 import { getExitEquivalence } from "../Fx/internal/equivalence.js";
 import { YieldableFx } from "../Fx/internal/yieldable.js";
@@ -30,13 +33,92 @@ import { FxTypeId, isFx } from "../Fx/TypeId.js";
 import * as Sink from "../Sink/Sink.js";
 import * as Subject from "../Subject/Subject.js";
 import * as Versioned from "../Versioned/Versioned.js";
+import { hasProperty } from "effect/Predicate";
+/**
+ * Runtime symbol identifying writable RefSubject values.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Provides stable runtime identity for RefSubject values without relying on classes or a renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration performs no acquisition and retains no resources. Implementations preserve
+ * source errors, services, and lifetime.
+ *
+ * @since 1.18.0
+ * @category Type identity
+ */
 export const RefSubjectTypeId = Symbol.for("@typed/fx/RefSubject");
+/**
+ * Runtime symbol identifying read-only Computed values.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Provides stable runtime identity for Computed values without relying on classes or a renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration performs no acquisition and retains no resources. Implementations preserve
+ * source errors, services, and lifetime.
+ *
+ * @since 1.18.0
+ * @category Type identity
+ */
 export const ComputedTypeId = Symbol.for("@typed/fx/Computed");
+/**
+ * Runtime symbol identifying conditionally available Filtered values.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Provides stable runtime identity for Filtered values without relying on classes or a renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration performs no acquisition and retains no resources. Implementations preserve
+ * source errors, services, and lifetime.
+ *
+ * @since 1.18.0
+ * @category Type identity
+ */
 export const FilteredTypeId = Symbol.for("@typed/fx/Filtered");
-export const CurrentComputedBehavior = ServiceMap.Reference("@typed/fx/CurrentComputedBehavior", {
+/**
+ * Selects whether a computed Fx observes only its current value or also follows later pushes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `"multiple"` (the default) emits the current value and then follows distinct source pushes.
+ * `"one"` emits only the current value. Hydration temporarily uses `"one"` when it must resolve a
+ * single server value without leaving a live observation running.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is an Effect Context reference with a default value, not mutable global state. Supplying a
+ * value changes computed observation only in the provided Effect context; the observing Scope
+ * still owns any subscription created by `"multiple"`.
+ *
+ * @since 1.18.0
+ * @category Observation policy
+ */
+export const CurrentComputedBehavior = Context.Reference("@typed/fx/CurrentComputedBehavior", {
     defaultValue: () => "multiple",
 });
-const checkIsMultiple = (ctx) => ServiceMap.getReferenceUnsafe(ctx, CurrentComputedBehavior) === "multiple";
+const checkIsMultiple = (ctx) => Context.getUnsafe(ctx, CurrentComputedBehavior) === "multiple";
+function holdInContext(fx) {
+    const contexts = new WeakMap();
+    return unwrap(Effect.map(Effect.context(), (context) => {
+        let shared = contexts.get(context);
+        if (!shared) {
+            shared = Subject.hold(fx);
+            contexts.set(context, shared);
+        }
+        return shared;
+    }));
+}
 class ComputedImpl extends Versioned.VersionedTransform {
     [ComputedTypeId] = ComputedTypeId;
     _computed;
@@ -46,20 +128,145 @@ class ComputedImpl extends Versioned.VersionedTransform {
         super(input, (fx) => fxMapEffect(fx, f), Effect.flatMap(f));
         this.input = input;
         this.f = f;
-        this._computed = Subject.hold(unwrap(Effect.map(Effect.services(), (ctx) => {
+        this._computed = holdInContext(unwrap(Effect.map(Effect.context(), (ctx) => {
             if (checkIsMultiple(ctx)) {
-                return fromYieldable(input).pipe(continueWith(() => input), skipRepeats, fxMapEffect(f));
+                return fxFromEffect(input).pipe(continueWith(() => input), skipRepeats, fxMapEffect(f));
             }
-            return fxFromEffect(Effect.flatMap(input.asEffect(), f));
+            return fxFromEffect(Effect.flatMap(input, f));
         })));
     }
     run(sink) {
         return this._computed.run(sink);
     }
 }
+/**
+ * Builds a read-only Computed projection from a Versioned source.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Applies the same Effectful projection to current reads and pushed versions, preserving all three
+ * Versioned channels without granting writes to the source.
+ *
+ * ## Ownership and lifetime
+ *
+ * Current reads cache the transformed input by source version within each Effect Context. The
+ * pushed channel uses `Subject.hold`: observers with the same Context object share one upstream
+ * session and its retained projection; distinct Context objects have separate sessions. The last
+ * observer ends its session and clears its held value. The observing Scope owns cleanup.
+ *
+ * @since 1.18.0
+ * @category Derived queries
+ */
 export function makeComputed(input, f) {
     return new ComputedImpl(input, f);
 }
+/**
+ * Stateful scan over a `RefSubject` / `Computed`, producing a `Computed` of the accumulated state.
+ *
+ * Fx subscriptions follow `Fx.scan` semantics (emit `initial`, then fold each source value).
+ * Effect sampling accumulates across source versions via a private state ref (do not mix heavy
+ * subscribe + sample on the same scan if you need a single shared accumulator).
+ *
+ * @remarks
+ * ## Why
+ *
+ * Stateful scan over a `RefSubject` / `Computed`, producing a `Computed` of the accumulated state.
+ * Fx subscriptions follow `Fx.scan` semantics (emit `initial`, then fold each source value).
+ * Effect sampling accumulates across source versions via a private state ref (do not mix heavy
+ * subscribe + sample on the same scan if you need a single shared accumulator). The result remains
+ * a lazy view rather than a duplicated mutable value.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each Effect Context object gets a private current-read accumulator, advanced after a successful
+ * fold for a new source version. The pushed channel runs `Fx.scanEffect` from `initial` inside
+ * `Subject.hold`: observers using the same Context share that active scan and retained result.
+ * The last observer ends its session and clears its held value. The observing Scope owns
+ * subscription cleanup. Read accumulators are weakly held by Context and need no finalizer.
+ *
+ * @since 1.0.0
+ * @category Accumulation
+ */
+export const scan = dual(3, function scan(versioned, initial, f) {
+    return new ComputedScanImpl(versioned, initial, (s, a) => Effect.succeed(f(s, a)));
+});
+/**
+ * Effectful stateful scan over a `RefSubject` / `Computed`, producing a `Computed` of the accumulated state.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Effectful stateful scan over a `RefSubject` / `Computed`, producing a `Computed` of the
+ * accumulated state. The result remains a lazy view rather than a duplicated mutable value.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each Effect Context object gets a private current-read accumulator. It advances only after `f`
+ * succeeds, so a typed failure leaves the previous state intact. The pushed channel runs
+ * `Fx.scanEffect` from `initial` inside `Subject.hold`: observers using the same Context share
+ * that active scan and retained result; each fold requires `R3`. The last observer ends its
+ * session and clears its held value. The observing Scope owns cleanup. Read accumulators are
+ * weakly held by Context and need no finalizer.
+ *
+ * @since 1.0.0
+ * @category Accumulation
+ */
+export const scanEffect = dual(3, function scanEffect(versioned, initial, f) {
+    return new ComputedScanImpl(versioned, initial, f);
+});
+class ComputedScanImpl extends Versioned.VersionedTransform {
+    [ComputedTypeId] = ComputedTypeId;
+    _computed;
+    input;
+    initial;
+    f;
+    constructor(input, initial, f) {
+        const states = new WeakMap();
+        super(input, (fx) => fxScanEffect(fx, initial, f), (effect) => Effect.contextWith((context) => {
+            let state = states.get(context);
+            if (!state) {
+                state = MutableRef.make(initial);
+                states.set(context, state);
+            }
+            const current = state;
+            return Effect.flatMap(effect, (a) => Effect.flatMap(f(MutableRef.get(current), a), (next) => Effect.sync(() => {
+                MutableRef.set(current, next);
+                return next;
+            })));
+        }));
+        this.input = input;
+        this.initial = initial;
+        this.f = f;
+        this._computed = holdInContext(unwrap(Effect.map(Effect.context(), (ctx) => {
+            if (checkIsMultiple(ctx)) {
+                return fxFromEffect(input).pipe(continueWith(() => input), skipRepeats, fxScanEffect(initial, f));
+            }
+            return fxFromEffect(Effect.flatMap(input, (a) => f(initial, a)));
+        })));
+    }
+    run(sink) {
+        return this._computed.run(sink);
+    }
+}
+/**
+ * Builds a Filtered view from the three channels of a Versioned source.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Applies `f` to current reads and later pushes while preserving absence as Filtered semantics:
+ * Effect reads fail with `NoSuchElementError`, whereas the Fx channel simply omits absent values.
+ *
+ * ## Ownership and lifetime
+ *
+ * Sampled results and pushed sessions are isolated by Effect Context identity. Within one Context,
+ * current reads cache by source version and observers share the active held projection. Its
+ * Effect read fails with NoSuchElement while absent; the observing Scope owns its subscription.
+ *
+ * @since 1.18.0
+ * @category Optional queries
+ */
 export function makeFiltered(input, f) {
     return new FilteredImpl(input, f);
 }
@@ -69,14 +276,14 @@ class FilteredImpl extends Versioned.VersionedTransform {
     input;
     f;
     constructor(input, f) {
-        super(input, (fx) => fxFilterMapEffect(fx, f), (effect) => Effect.flatMap(Effect.flatMap(effect, f), (option) => option.asEffect()));
+        super(input, (fx) => fxFilterMapEffect(fx, f), (effect) => Effect.flatMap(Effect.flatMap(effect, f), Effect.fromOption));
         this.input = input;
         this.f = f;
-        this._computed = Subject.hold(unwrap(Effect.map(Effect.services(), (ctx) => {
+        this._computed = holdInContext(unwrap(Effect.map(Effect.context(), (ctx) => {
             if (checkIsMultiple(ctx)) {
-                return fromYieldable(input).pipe(continueWith(() => input), skipRepeats, fxFilterMapEffect(f));
+                return fxFromEffect(input).pipe(continueWith(() => input), skipRepeats, fxFilterMapEffect(f));
             }
-            return fxCompact(fxFromEffect(Effect.flatMap(input.asEffect(), f)));
+            return fxCompact(fxFromEffect(Effect.flatMap(input, f)));
         })));
     }
     run(sink) {
@@ -86,6 +293,7 @@ class FilteredImpl extends Versioned.VersionedTransform {
         return new ComputedImpl(this.input, this.f);
     }
 }
+let nextTransactionOrder = 0;
 class RefSubjectCore {
     initial;
     subject;
@@ -93,6 +301,7 @@ class RefSubjectCore {
     scope;
     deferredRef;
     semaphore;
+    transactionOrder = nextTransactionOrder++;
     constructor(initial, subject, services, scope, deferredRef, semaphore) {
         this.initial = initial;
         this.subject = subject;
@@ -103,10 +312,116 @@ class RefSubjectCore {
     }
     _fiber = undefined;
 }
-function getSetDelete(ref) {
+function combineTransactionCores(accesses) {
+    return [...new Set(accesses.flatMap((access) => access.cores))].sort((left, right) => left.transactionOrder - right.transactionOrder);
+}
+function getTupleTransactionAccess(refs) {
+    const accessEffects = refs.map(getTransactionAccess);
+    if (!accessEffects.every((access) => access !== undefined)) {
+        return undefined;
+    }
+    return Effect.map(Effect.all(accessEffects, UNBOUNDED), (accessOptions) => Option.map(Option.all(accessOptions), (accesses) => ({
+        cores: combineTransactionCores(accesses),
+        getSetDelete: (recordCommit) => {
+            const transactions = accesses.map((access) => access.getSetDelete(recordCommit));
+            return {
+                get: Effect.all(transactions.map((transaction) => transaction.get), UNBOUNDED),
+                set: (value) => Effect.all(transactions.map((transaction, index) => transaction.set(value[index])), UNBOUNDED),
+                delete: Effect.map(Effect.all(transactions.map((transaction) => transaction.delete), UNBOUNDED), Option.all),
+            };
+        },
+    })));
+}
+function getStructTransactionAccess(refs) {
+    const keys = Object.keys(refs);
+    const accessEffects = keys.map((key) => getTransactionAccess(refs[key]));
+    if (!accessEffects.every((access) => access !== undefined)) {
+        return undefined;
+    }
+    return Effect.map(Effect.all(accessEffects, UNBOUNDED), (accessOptions) => Option.map(Option.all(accessOptions), (accesses) => ({
+        cores: combineTransactionCores(accesses),
+        getSetDelete: (recordCommit) => {
+            const transactions = accesses.map((access) => access.getSetDelete(recordCommit));
+            return {
+                get: Effect.map(Effect.all(transactions.map((transaction) => transaction.get), UNBOUNDED), (values) => Object.fromEntries(keys.map((key, index) => [key, values[index]]))),
+                set: (value) => Effect.all(transactions.map((transaction, index) => transaction.set(value[keys[index]])), UNBOUNDED),
+                delete: Effect.map(Effect.all(transactions.map((transaction) => transaction.delete), UNBOUNDED), (values) => Option.all(Object.fromEntries(keys.map((key, index) => [key, values[index]])))),
+            };
+        },
+    })));
+}
+function getTransactionAccess(ref) {
+    if (ref instanceof RefSubjectImpl) {
+        return Effect.succeed(Option.some({
+            cores: [ref.core],
+            getSetDelete: (recordCommit) => getSetDelete(ref.core, (exit) => recordCommit([ref.core, exit, ref.core.deferredRef.version])),
+        }));
+    }
+    if (ref instanceof RefSubjectSimpleTransform)
+        return getTransactionAccess(ref.ref);
+    if (ref instanceof RefSubjectTransform) {
+        const accessEffect = getTransactionAccess(ref.ref);
+        if (!accessEffect)
+            return undefined;
+        return Effect.map(accessEffect, Option.map((access) => ({
+            cores: access.cores,
+            getSetDelete: (recordCommit) => {
+                const transaction = access.getSetDelete(recordCommit);
+                return {
+                    get: Effect.map(transaction.get, ref.toB),
+                    set: (value) => Effect.map(transaction.set(ref.toA(value)), ref.toB),
+                    delete: Effect.map(transaction.delete, Option.map(ref.toB)),
+                };
+            },
+        })));
+    }
+    if (ref instanceof RefSubjectTuple)
+        return getTupleTransactionAccess(ref.refs);
+    if (ref instanceof RefSubjectStruct)
+        return getStructTransactionAccess(ref.refs);
+    if (typeof ref === "function") {
+        const service = ref.service;
+        if (Effect.isEffect(service)) {
+            return Effect.flatMap(service, (providedRef) => {
+                const accessEffect = getTransactionAccess(providedRef);
+                return accessEffect ?? Effect.succeed(Option.none());
+            });
+        }
+    }
+    return undefined;
+}
+function withTransactionLocks(cores, effect) {
+    let locked = effect;
+    for (let index = cores.length - 1; index >= 0; index--) {
+        locked = cores[index].semaphore.withPermits(1)(locked);
+    }
+    return locked;
+}
+function runTransaction(access, run) {
+    return Effect.uninterruptibleMask((restore) => {
+        const commits = [];
+        const transaction = restore(withTransactionLocks(access.cores, Effect.suspend(() => run(access.getSetDelete((commit) => {
+            commits.push(commit);
+        })))));
+        return Effect.flatMap(Effect.exit(transaction), (exit) => Effect.andThen(Effect.forEach(commits, ([core, commit, version]) => sendCurrentEvent(core, commit, version), {
+            discard: true,
+        }), exit));
+    });
+}
+function sendCurrentEvent(core, commit, version) {
+    return Effect.suspend(() => {
+        const current = MutableRef.get(core.deferredRef.current);
+        return core.deferredRef.version === version &&
+            Option.isSome(current) &&
+            core.deferredRef.eq(current.value, commit)
+            ? sendEvent(core, commit)
+            : Effect.void;
+    });
+}
+function getSetDelete(ref, recordCommit) {
     return {
         get: getOrInitializeCore(ref, false),
-        set: (a) => setCore(ref, a),
+        set: (a) => bufferSuccessCore(ref, a, recordCommit),
         delete: deleteCore(ref),
     };
 }
@@ -116,7 +431,6 @@ class RefSubjectImpl extends YieldableFx {
     version;
     interrupt;
     subscriberCount;
-    getSetDelete;
     core;
     constructor(core) {
         super();
@@ -124,25 +438,25 @@ class RefSubjectImpl extends YieldableFx {
         this.version = Effect.sync(() => core.deferredRef.version);
         this.interrupt = Effect.provide(interruptCore(core), core.services);
         this.subscriberCount = Effect.provide(core.subject.subscriberCount, core.services);
-        this.getSetDelete = getSetDelete(core);
         this.updates = this.updates.bind(this);
         this.onSuccess = this.onSuccess.bind(this);
         this.onFailure = this.onFailure.bind(this);
     }
     run(sink) {
+        const subscribe = Effect.provide(this.core.subject.run(sink), this.core.services);
         return Effect.matchCauseEffect(getOrInitializeCore(this.core, true), {
-            onFailure: (cause) => sink.onFailure(cause),
-            onSuccess: () => Effect.provide(this.core.subject.run(sink), this.core.services),
+            onFailure: () => subscribe,
+            onSuccess: () => subscribe,
         });
     }
     updates(run) {
-        return this.core.semaphore.withPermits(1)(run(this.getSetDelete));
+        return updateCore(this.core, (recordCommit) => run(getSetDelete(this.core, recordCommit)));
     }
     onSuccess(value) {
-        return setCore(this.core, value);
+        return updateCore(this.core, (recordCommit) => bufferSuccessCore(this.core, value, recordCommit));
     }
     onFailure(cause) {
-        return onFailureCore(this.core, cause);
+        return updateCore(this.core, (recordCommit) => bufferFailureCore(this.core, cause, recordCommit));
     }
     toEffect() {
         return getOrInitializeCore(this.core, true);
@@ -151,6 +465,31 @@ class RefSubjectImpl extends YieldableFx {
 /**
  * Creates a new `RefSubject` from a value, `Effect`, or `Fx`.
  *
+ * @remarks
+ * ## Why
+ *
+ * `RefSubject` keeps current state and pushed changes independent of any UI
+ * renderer. Domain transitions can therefore be constructed, composed, and
+ * tested with Effect alone; rendering is one optional consumer of the state.
+ * Plain values, Effect programs, pull-based Effect `Stream`s, and push-based
+ * `Fx` sources all enter through the same state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Creation requires an Effect `Scope`. That scope owns source acquisition,
+ * subscriptions, and finalization. The returned `RefSubject` exposes the
+ * source error type when read or observed, while construction itself cannot
+ * fail. Closing the scope interrupts a live source and releases its resources.
+ *
+ * ## Initialization
+ *
+ * Calling `make` is lazy because it returns an Effect: nothing is allocated and no source runs
+ * until that creation Effect is executed. After creation, a plain value is immediately available.
+ * An Effect input runs once on the first current read or observation. Fx and Stream inputs instead
+ * start one shared source run when the creation Effect executes; reads wait for their first value
+ * or failure and later emissions replace the retained current state. Equality and buffering
+ * behavior can be customized with `RefSubjectOptions`.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -184,7 +523,7 @@ class RefSubjectImpl extends YieldableFx {
  * ```
  *
  * @since 1.0.0
- * @category constructors
+ * @category Constructors
  */
 export function make(effect, options) {
     if (isFx(effect)) {
@@ -203,6 +542,19 @@ export function make(effect, options) {
 /**
  * Creates a `RefSubject` from an `Effect`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Makes effect acquisition explicit while normalizing it into current RefSubject state and
+ * subsequent pushed versions.
+ *
+ * ## Ownership and lifetime
+ *
+ * The creation Effect requires Scope and the source's services, which it captures for the private
+ * initializer Scope. The source Effect itself stays deferred until the first current read or
+ * observation and runs at most once. Source failures remain visible on reads and observations;
+ * closing the creation Scope interrupts an initializer that is still running.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -219,7 +571,7 @@ export function make(effect, options) {
  * ```
  *
  * @since 1.0.0
- * @category constructors
+ * @category Source adapters
  */
 export function fromEffect(effect, options) {
     return Effect.map(makeCore(effect, options), (core) => new RefSubjectImpl(core));
@@ -227,6 +579,17 @@ export function fromEffect(effect, options) {
 /**
  * Creates a `RefSubject` from an `Fx`, tracking the latest emitted value.
  *
+ * @remarks
+ * ## Why
+ *
+ * Makes fx acquisition explicit while normalizing it into current RefSubject state and subsequent
+ * pushed versions.
+ *
+ * ## Ownership and lifetime
+ *
+ * The creation Effect requires Scope. It owns initializer acquisition, live source subscriptions,
+ * and cleanup; source failures and services stay on reads and pushes.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -247,35 +610,136 @@ export function fromEffect(effect, options) {
  * ```
  *
  * @since 1.0.0
- * @category constructors
+ * @category Source adapters
  */
 export function fromFx(fx, options) {
     return Effect.gen(function* () {
         const core = yield* makeDeferredCore(options);
         const ref = new RefSubjectImpl(core);
-        yield* Effect.forkIn(fx.run(Sink.make((cause) => onFailureCore(core, cause), (value) => setCore(core, value))), core.scope, { startImmediately: true });
+        yield* Effect.forkIn(fx.run(Sink.make((cause) => updateCore(core, (recordCommit) => bufferFailureCore(core, cause, recordCommit)), (value) => updateCore(core, (recordCommit) => bufferSuccessCore(core, value, recordCommit)))), core.scope, { startImmediately: true });
         return ref;
     });
 }
+/**
+ * Creates a RefSubject that tracks the latest value emitted by an Effect Stream.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Bridges a pull-based Stream into renderer-independent state: each emitted value enters the
+ * RefSubject's serialized commit path, while a stream failure becomes the ref's current and pushed
+ * failure.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction forks stream consumption immediately into the RefSubject's private Scope and cannot
+ * fail. `R` is required while constructing that fiber; closing the outer Scope interrupts it.
+ * Before the first value or failure, a current read waits for initialization. Later reads and pushes
+ * expose `E`.
+ *
+ * @since 1.18.0
+ * @category Source adapters
+ */
 export function fromStream(stream, options) {
     return Effect.gen(function* () {
         const core = yield* makeDeferredCore(options);
         const ref = new RefSubjectImpl(core);
-        yield* Effect.forkIn(stream.pipe(redirectCause(core), Stream.runForEach((value) => setCore(core, value))), core.scope, { startImmediately: true });
+        yield* Effect.forkIn(stream.pipe(redirectCause(core), Stream.runForEach((value) => updateCore(core, (recordCommit) => bufferSuccessCore(core, value, recordCommit)))), core.scope, { startImmediately: true });
         return ref;
     });
 }
+/**
+ * Creates a `RefSubject` from an `Option` value.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Stores the Option itself in writable state. `None` is an ordinary current value and does not add
+ * `NoSuchElementError`; callers opt into absence semantics with `compact`, or a fallback with
+ * `getOrElse`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction requires Scope because it delegates to `make`, but the supplied Option needs no
+ * services and cannot fail. The returned RefSubject owns and publishes subsequent Option writes.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import * as RefSubject from "@typed/fx/RefSubject"
+ *
+ * const program = Effect.gen(function* () {
+ *   const ref = yield* RefSubject.fromOption(Option.some(42))
+ *   const value = yield* ref
+ *   console.log(Option.isSome(value)) // true
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Source adapters
+ */
+export function fromOption(option, options) {
+    return make(option, options);
+}
+/**
+ * Creates a `RefSubject` from a nullable value (null/undefined become `Option.none()`).
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import * as RefSubject from "@typed/fx/RefSubject"
+ *
+ * const program = Effect.gen(function* () {
+ *   const ref = yield* RefSubject.fromNullable("hello")
+ *   const value = yield* ref
+ *   console.log(Option.isSome(value)) // true
+ *
+ *   const empty = yield* RefSubject.fromNullable(null)
+ *   const none = yield* empty
+ *   console.log(Option.isNone(none)) // true
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Source adapters
+ */
+function optionFromNullable(value) {
+    return value === null || value === undefined
+        ? Option.none()
+        : Option.some(value);
+}
+/**
+ * Creates Option-valued RefSubject state from a nullable input.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Converts `null` and `undefined` to `Option.none` and every other value to `Option.some`, then
+ * stores that Option in a writable RefSubject. It does not create Filtered state or add
+ * `NoSuchElementError`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction requires Scope because it delegates to `make`; it needs no services and cannot
+ * fail. The returned RefSubject owns and publishes subsequent Option writes.
+ *
+ * @since 1.18.0
+ * @category Source adapters
+ */
+export function fromNullable(value, options) {
+    return make(optionFromNullable(value), options);
+}
 function redirectCause(core) {
-    return Stream.catchCause((cause) => Stream.unwrap(Effect.as(onFailureCore(core, cause), Stream.empty)));
+    return Stream.catchCause((cause) => Stream.unwrap(Effect.as(updateCore(core, (recordCommit) => bufferFailureCore(core, cause, recordCommit)), Stream.empty)));
 }
 function makeCore(initial, options, deferredRef) {
     return Effect.gen(function* () {
-        const services = yield* Effect.services();
-        const scope = yield* Scope.fork(ServiceMap.get(services, Scope.Scope));
+        const services = yield* Effect.context();
+        const scope = yield* Scope.fork(Context.get(services, Scope.Scope));
         const id = yield* Effect.withFiber((fiber) => Effect.succeed(fiber.id));
         const subject = new Subject.HoldSubjectImpl();
         const core = new RefSubjectCore(initial, subject, services, scope, deferredRef ??
-            DeferredRef.unsafeMake(id, getExitEquivalence(options?.eq ?? equals), subject.lastValue), Effect.makeSemaphoreUnsafe(1));
+            DeferredRef.unsafeMake(id, getExitEquivalence(options?.eq ?? equals), subject.lastValue), Semaphore.makeUnsafe(1));
         yield* Scope.addFinalizer(scope, core.subject.interrupt);
         return core;
     });
@@ -283,7 +747,7 @@ function makeCore(initial, options, deferredRef) {
 function makeDeferredCore(options) {
     return Effect.gen(function* () {
         const deferredRef = yield* DeferredRef.make(getExitEquivalence(options?.eq ?? equals));
-        return yield* makeCore(deferredRef.asEffect(), options, deferredRef);
+        return yield* makeCore(deferredRef, options, deferredRef);
     });
 }
 function getOrInitializeCore(core, lockInitialize) {
@@ -292,30 +756,51 @@ function getOrInitializeCore(core, lockInitialize) {
             return initializeCoreAndTap(core, lockInitialize);
         }
         else {
-            return core.deferredRef.asEffect();
+            return core.deferredRef;
         }
     });
 }
 function initializeCoreEffect(core, lock) {
+    let completed = false;
     const initialize = Effect.onExit(Effect.provide(core.initial, core.services), (exit) => Effect.sync(() => {
+        completed = true;
         core._fiber = undefined;
         core.deferredRef.done(exit);
     }));
-    return Effect.flatMap(Effect.forkIn(lock ? core.semaphore.withPermits(1)(initialize) : initialize, core.scope), (fiber) => Effect.sync(() => (core._fiber = fiber)));
+    const isSourceBacked = core.initial === core.deferredRef;
+    return Effect.flatMap(Effect.forkIn(lock && !isSourceBacked ? core.semaphore.withPermits(1)(initialize) : initialize, core.scope, 
+    // Acquire the initializer's permit before a competing update can hold it while awaiting us.
+    { startImmediately: true }), (fiber) => Effect.sync(() => {
+        // A synchronous initializer has already cleared its ownership in onExit.
+        if (!completed)
+            core._fiber = fiber;
+        return fiber;
+    }));
 }
 function initializeCoreAndTap(core, lock) {
-    return Effect.flatMapEager(initializeCoreEffect(core, lock), () => tapEventCore(core, core.deferredRef.asEffect()));
+    return Effect.flatMapEager(initializeCoreEffect(core, lock), () => 
+    // Kind of weird hack, but this second clause will happen for HydrationRefs that are already hydrated
+    core.deferredRef.current === core.subject.lastValue
+        ? tapEventCore(core, core.deferredRef)
+        : core.deferredRef);
+}
+function updateCore(core, run) {
+    return Effect.uninterruptibleMask((restore) => {
+        const commits = [];
+        const transaction = restore(core.semaphore.withPermits(1)(Effect.suspend(() => run((commit) => {
+            commits.push(commit);
+        }))));
+        return Effect.flatMap(Effect.exit(transaction), (exit) => Effect.andThen(Effect.forEach(commits, (commit) => sendEvent(core, commit), { discard: true }), exit));
+    });
 }
 function setCore(core, a) {
     return Effect.suspend(() => {
         const exit = Exit.succeed(a);
         if (core.deferredRef.done(exit)) {
-            // If the value changed, send an event
-            return Effect.as(sendEvent(core, exit), a);
+            return Effect.succeed(Option.some(exit));
         }
         else {
-            // Otherwise, just return the current value
-            return Effect.succeed(a);
+            return Effect.succeed(Option.none());
         }
     });
 }
@@ -323,13 +808,26 @@ function onFailureCore(core, cause) {
     const exit = Exit.failCause(cause);
     return Effect.suspend(() => {
         if (core.deferredRef.done(exit)) {
-            return sendEvent(core, exit);
+            return Effect.succeed(Option.some(exit));
         }
         else {
-            return Effect.void;
+            return Effect.succeed(Option.none());
         }
     });
 }
+function bufferSuccessCore(core, value, recordCommit) {
+    return Effect.map(setCore(core, value), (commit) => {
+        if (Option.isSome(commit))
+            recordCommit(commit.value);
+        return value;
+    });
+}
+function bufferFailureCore(core, cause, recordCommit) {
+    return Effect.asVoid(Effect.map(onFailureCore(core, cause), (commit) => {
+        if (Option.isSome(commit))
+            recordCommit(commit.value);
+    }));
+}
 function interruptCore(core) {
     return Effect.withFiber((fiber) => {
         core.deferredRef.reset();
@@ -363,6 +861,17 @@ function sendEvent(core, exit) {
 /**
  * Sets the value of a `RefSubject`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Sets the value of a `RefSubject`. The transition is serialized at the RefSubject rather than
+ * coordinated by callers or UI components.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running set performs one serialized subject transition and resolves with its committed value. It
+ * acquires no resource; failures and services remain those of the source ref.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -384,7 +893,7 @@ function sendEvent(core, exit) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category State updates
  */
 export const set = dual(2, function set(ref, a) {
     return ref.updates((ref) => ref.set(a));
@@ -392,6 +901,17 @@ export const set = dual(2, function set(ref, a) {
 /**
  * Resets a `RefSubject` to its initial value, returning the previous value if it existed.
  *
+ * @remarks
+ * ## Why
+ *
+ * Resets a `RefSubject` to its initial value, returning the previous value if it existed. The
+ * transition is serialized at the RefSubject rather than coordinated by callers or UI components.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running reset performs one serialized subject transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @example
  * ```ts
  * import { Effect, Option } from "effect"
@@ -415,7 +935,7 @@ export const set = dual(2, function set(ref, a) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category State updates
  */
 export function reset(ref) {
     return ref.updates((ref) => ref.delete);
@@ -445,12 +965,23 @@ export {
  * ```
  *
  * @since 1.20.0
- * @category combinators
+ * @category State updates
  */
 reset as delete, };
 /**
  * Updates a `RefSubject` using an `Effect`ful function.
  *
+ * @remarks
+ * ## Why
+ *
+ * Updates a `RefSubject` using an `Effect`ful function. The transition is serialized at the
+ * RefSubject rather than coordinated by callers or UI components.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running update effect performs one serialized subject transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -470,7 +1001,7 @@ reset as delete, };
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category State updates
  */
 export const updateEffect = dual(2, function updateEffect(ref, f) {
     return ref.updates((ref) => Effect.flatMap(Effect.flatMap(ref.get, f), ref.set));
@@ -478,6 +1009,26 @@ export const updateEffect = dual(2, function updateEffect(ref, f) {
 /**
  * Updates a `RefSubject` using a pure function.
  *
+ * @remarks
+ * ## Why
+ *
+ * `update` expresses a state transition where the state lives, without moving
+ * transition logic into a component or renderer. The same function can run in
+ * application code, tests, workers, event handlers, or a Typed template.
+ *
+ * ## Ownership and lifetime
+ *
+ * The update runs inside the RefSubject's existing synchronized update
+ * boundary: it reads the committed value, derives the next value, commits it,
+ * and publishes that change. It acquires no independent resource and retains
+ * the subject's existing error and service channels.
+ *
+ * ## Concurrency and failure
+ *
+ * Concurrent updates are serialized by the subject core so each function sees
+ * a committed value. A pure updater adds no error channel; failures already
+ * associated with reading or writing the RefSubject remain explicit in `E`.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -499,7 +1050,7 @@ export const updateEffect = dual(2, function updateEffect(ref, f) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category State updates
  */
 export const update = dual(2, function update(ref, f) {
     return updateEffect(ref, (value) => Effect.succeed(f(value)));
@@ -507,6 +1058,18 @@ export const update = dual(2, function update(ref, f) {
 /**
  * Modifies a `RefSubject` using an `Effect`ful function that returns both a result and a new value.
  *
+ * @remarks
+ * ## Why
+ *
+ * Modifies a `RefSubject` using an `Effect`ful function that returns both a result and a new
+ * value. The transition is serialized at the RefSubject rather than coordinated by callers or UI
+ * components.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running modify effect performs one serialized subject transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -527,14 +1090,25 @@ export const update = dual(2, function update(ref, f) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Transactions
  */
 export const modifyEffect = dual(2, function modifyEffect(ref, f) {
-    return ref.updates((ref) => Effect.flatMap(ref.get, (value) => Effect.flatMap(f(value), ([b, a]) => Effect.flatMap(ref.set(a), () => Effect.succeed(b)))));
+    return ref.updates((ref) => Effect.flatMap(ref.get, (value) => Effect.flatMap(f(value), ([b, a]) => Effect.as(ref.set(a), b))));
 });
 /**
  * Modifies a `RefSubject` using a pure function that returns both a result and a new value.
  *
+ * @remarks
+ * ## Why
+ *
+ * Modifies a `RefSubject` using a pure function that returns both a result and a new value. The
+ * transition is serialized at the RefSubject rather than coordinated by callers or UI components.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running modify performs one serialized subject transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -553,7 +1127,7 @@ export const modifyEffect = dual(2, function modifyEffect(ref, f) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Transactions
  */
 export const modify = dual(2, function modify(ref, f) {
     return modifyEffect(ref, (value) => Effect.succeed(f(value)));
@@ -561,6 +1135,16 @@ export const modify = dual(2, function modify(ref, f) {
 /**
  * Checks if a value is a `RefSubject`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Checks if a value is a `RefSubject`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The derived ref owns no independent state or subscription. It follows the source lifetime and
+ * routes writes through the source's synchronized update boundary.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -578,14 +1162,45 @@ export const modify = dual(2, function modify(ref, f) {
  * ```
  *
  * @since 1.0.0
- * @category guards
+ * @category Type guards
  */
 export function isRefSubject(value) {
-    return value && typeof value === "object" && value[RefSubjectTypeId] === RefSubjectTypeId;
+    return hasProperty(value, RefSubjectTypeId) && value[RefSubjectTypeId] === RefSubjectTypeId;
 }
 const isRefSubjectDataFirst = (args) => isRefSubject(args[0]);
 /**
+ * Tests whether a value carries the public Computed TypeId.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Uses the TypeId contract rather than a concrete implementation class, so custom Computed values
+ * and service facades participate in the same runtime guard.
+ *
+ * ## Ownership and lifetime
+ *
+ * This synchronous predicate performs no Effect, subscription, or acquisition.
+ *
+ * @since 1.18.0
+ * @category Type guards
+ */
+export function isComputed(value) {
+    return hasProperty(value, ComputedTypeId) && value[ComputedTypeId] === ComputedTypeId;
+}
+/**
+ * Runs an effect that can modify a `RefSubject` transactionally, with optional interrupt handling.
+ *
+ * @remarks
+ * ## Why
+ *
  * Runs an effect that can modify a `RefSubject` transactionally, with optional interrupt handling.
+ * The transition is serialized at the RefSubject rather than coordinated by callers or UI
+ * components.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running run updates performs one serialized subject transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
  *
  * @example
  * ```ts
@@ -616,7 +1231,7 @@ const isRefSubjectDataFirst = (args) => isRefSubject(args[0]);
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Transactions
  */
 export const runUpdates = dual(isRefSubjectDataFirst, function runUpdates(ref, f, options) {
     if (options === undefined) {
@@ -632,6 +1247,17 @@ export const runUpdates = dual(isRefSubjectDataFirst, function runUpdates(ref, f
 /**
  * Increments a numeric `RefSubject` by 1.
  *
+ * @remarks
+ * ## Why
+ *
+ * Increments a numeric `RefSubject` by 1. The transition is serialized at the RefSubject rather
+ * than coordinated by callers or UI components.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running increment performs one serialized subject transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -651,7 +1277,7 @@ export const runUpdates = dual(isRefSubjectDataFirst, function runUpdates(ref, f
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category State updates
  */
 export function increment(ref) {
     return update(ref, (value) => value + 1);
@@ -659,6 +1285,17 @@ export function increment(ref) {
 /**
  * Decrements a numeric `RefSubject` by 1.
  *
+ * @remarks
+ * ## Why
+ *
+ * Decrements a numeric `RefSubject` by 1. The transition is serialized at the RefSubject rather
+ * than coordinated by callers or UI components.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running decrement performs one serialized subject transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -678,7 +1315,7 @@ export function increment(ref) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category State updates
  */
 export function decrement(ref) {
     return update(ref, (value) => value - 1);
@@ -688,12 +1325,42 @@ const Variance = {
     _E: identity,
     _R: identity,
 };
+/**
+ * Creates a Context-backed RefSubject service facade and Layer constructors.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The returned class is simultaneously a service tag, a current-value Effect, an Fx source, and a
+ * writable RefSubject facade. This lets consumers read, observe, and update renderer-independent
+ * state without manually retrieving the underlying service from Context.
+ *
+ * ## Ownership and lifetime
+ *
+ * Calling `Service` is pure. `layer` installs an existing scoped RefSubject; `make` constructs one
+ * and installs it in a Layer. The Layer Scope owns the subject and its initializer subscription.
+ * Reads and pushes expose the declared `E` channel; construction requirements remain on the Layer,
+ * while consumers require only the generated `Self` service.
+ *
+ * @since 1.18.0
+ * @category Services
+ */
 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 RefSubjectService {
             /// Service
+            static {
+                // @effect-diagnostics-next-line floatingEffect:off
+                Object.assign(this, service);
+                Object.setPrototypeOf(this, Object.getPrototypeOf(service));
+                // @effect-diagnostics-next-line floatingEffect:off
+                Object.assign(this, Effectable.Prototype({
+                    label: "RefSubject.Service",
+                    evaluate: () => Effect.flatMap(service, identity),
+                }));
+            }
             static id = id;
             static service = service;
             static layer = (make) => Layer.effect(service, make);
@@ -703,21 +1370,21 @@ export function Service() {
             };
             // Fx
             static [FxTypeId] = Variance;
-            static run = (sink) => Effect.flatMap(service.asEffect(), (ref) => ref.run(sink));
+            static run = (sink) => Effect.flatMap(service, (ref) => ref.run(sink));
             // Sink
-            static onSuccess = (value) => Effect.flatMap(service.asEffect(), (ref) => ref.onSuccess(value));
-            static onFailure = (cause) => Effect.flatMap(service.asEffect(), (ref) => ref.onFailure(cause));
+            static onSuccess = (value) => Effect.flatMap(service, (ref) => ref.onSuccess(value));
+            static onFailure = (cause) => Effect.flatMap(service, (ref) => ref.onFailure(cause));
             /// Computed
             static [ComputedTypeId] = ComputedTypeId;
-            static version = Effect.flatMap(service.asEffect(), (ref) => ref.version);
+            static version = Effect.flatMap(service, (ref) => ref.version);
             // Subject
-            static subscriberCount = Effect.flatMap(service.asEffect(), (ref) => ref.subscriberCount);
-            static interrupt = Effect.flatMap(service.asEffect(), (ref) => ref.interrupt);
+            static subscriberCount = Effect.flatMap(service, (ref) => ref.subscriberCount);
+            static interrupt = Effect.flatMap(service, (ref) => ref.interrupt);
             // RefSubject
             static [RefSubjectTypeId] = RefSubjectTypeId;
-            static updates = (f) => Effect.flatMap(service.asEffect(), (ref) => ref.updates(f));
+            static updates = (f) => Effect.flatMap(service, (ref) => ref.updates(f));
             // Yieldable
-            static asEffect = () => Effect.flatMap(service.asEffect(), Effect.fromYieldable);
+            static override = Effect.flatten(service);
             static [Symbol.iterator] = function* () {
                 const ref = yield* service;
                 return yield* ref;
@@ -741,6 +1408,19 @@ function getDefaultBounds(options) {
  * Extract all values from an object using a Proxy.
  * Allows accessing nested properties of a `Computed` or `Filtered` object/array as individual computed values.
  *
+ * @remarks
+ * ## Why
+ *
+ * Lazily creates one property projection per accessed key and memoizes that projection on the
+ * JavaScript Proxy. A Computed or RefSubject source produces Computed properties; only a Filtered
+ * source produces Filtered properties and preserves conditional absence.
+ *
+ * ## Ownership and lifetime
+ *
+ * The Proxy caches derived view objects, not property values. Computed property reads expose only
+ * the source's `E`; Filtered property reads can additionally fail with `NoSuchElementError` while
+ * their source is absent. Each observed property follows the source and uses the observing Scope.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -769,7 +1449,7 @@ function getDefaultBounds(options) {
  * ```
  *
  * @since 2.0.0
- * @category combinators
+ * @category Derived queries
  */
 export const proxy = (source) => {
     const target = {};
@@ -784,6 +1464,20 @@ export const proxy = (source) => {
 /**
  * Transforms a `RefSubject`, `Computed`, or `Filtered` using an `Effect`ful function.
  *
+ * @remarks
+ * ## Why
+ *
+ * Applies one Effectful derivation to current reads and pushed versions. RefSubject and Computed
+ * inputs return Computed and add only `E2`; a Filtered input returns Filtered and preserves its
+ * conditional absence in addition to `E2`.
+ *
+ * ## Ownership and lifetime
+ *
+ * No callback runs until the result is read or observed. Computed results cannot become absent and
+ * do not add `NoSuchElementError`; only the Filtered overload can fail a current read for absence.
+ * Callback services and failures remain `R2` and `E2`, and the observing Scope owns subscription
+ * cleanup.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -810,7 +1504,7 @@ export const proxy = (source) => {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Derived queries
  */
 export const mapEffect = dual(2, function mapEffect(versioned, f) {
     return FilteredTypeId in versioned
@@ -820,6 +1514,25 @@ export const mapEffect = dual(2, function mapEffect(versioned, f) {
 /**
  * Transforms a `RefSubject`, `Computed`, or `Filtered` using a pure function.
  *
+ * @remarks
+ * ## Why
+ *
+ * `map` creates derived state instead of copying source state into a component.
+ * Reads and pushed updates remain connected to the original `Versioned` value,
+ * so a projection can be tested without rendering and consumed by any renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned `Computed` or `Filtered` view does not take ownership of the
+ * source. It follows the source lifetime and preserves its error and service
+ * channels. The pure mapping function adds neither resources nor failures.
+ *
+ * ## Re-computation
+ *
+ * The mapping function runs for the current value and subsequent committed
+ * source versions. Updates still occur on the writable source; the derived view
+ * is read-only unless a more specific bidirectional combinator is used.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -844,7 +1557,7 @@ export const mapEffect = dual(2, function mapEffect(versioned, f) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Derived queries
  */
 export const map = dual(2, function map(versioned, f) {
     return mapEffect(versioned, (a) => Effect.succeed(f(a)));
@@ -852,6 +1565,18 @@ export const map = dual(2, function map(versioned, f) {
 /**
  * Filters and transforms a `RefSubject`, `Computed`, or `Filtered` using an `Effect`ful function that returns an `Option`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Filters and transforms a `RefSubject`, `Computed`, or `Filtered` using an `Effect`ful function
+ * that returns an `Option`. Current reads and pushed versions use the same derivation, preventing
+ * snapshot and subscription behavior from diverging.
+ *
+ * ## Ownership and lifetime
+ *
+ * The filter map effect view retains no independent value. Its Effect read fails with NoSuchElement
+ * while absent; the observing Scope owns and finalizes its Fx subscription.
+ *
  * @example
  * ```ts
  * import { Effect, Option } from "effect"
@@ -871,7 +1596,7 @@ export const map = dual(2, function map(versioned, f) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Optional queries
  */
 export const filterMapEffect = dual(2, function filterMapEffect(versioned, f) {
     return new FilteredImpl(versioned, f);
@@ -879,6 +1604,18 @@ export const filterMapEffect = dual(2, function filterMapEffect(versioned, f) {
 /**
  * Filters and transforms a `RefSubject`, `Computed`, or `Filtered` using a pure function that returns an `Option`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Filters and transforms a `RefSubject`, `Computed`, or `Filtered` using a pure function that
+ * returns an `Option`. Current reads and pushed versions use the same derivation, preventing
+ * snapshot and subscription behavior from diverging.
+ *
+ * ## Ownership and lifetime
+ *
+ * The filter map view retains no independent value. Its Effect read fails with NoSuchElement
+ * while absent; the observing Scope owns and finalizes its Fx subscription.
+ *
  * @example
  * ```ts
  * import { Effect, Option } from "effect"
@@ -898,7 +1635,7 @@ export const filterMapEffect = dual(2, function filterMapEffect(versioned, f) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Optional queries
  */
 export const filterMap = dual(2, function filterMap(versioned, f) {
     return new FilteredImpl(versioned, (a) => Effect.succeed(f(a)));
@@ -906,6 +1643,18 @@ export const filterMap = dual(2, function filterMap(versioned, f) {
 /**
  * Converts a `Computed` or `Filtered` of `Option<A>` into a `Filtered<A>`, filtering out `None` values.
  *
+ * @remarks
+ * ## Why
+ *
+ * Converts a `Computed` or `Filtered` of `Option<A>` into a `Filtered<A>`, filtering out `None`
+ * values. Current reads and pushed versions use the same derivation, preventing snapshot and
+ * subscription behavior from diverging.
+ *
+ * ## Ownership and lifetime
+ *
+ * The compact view retains no independent value. Its Effect read fails with NoSuchElement
+ * while absent; the observing Scope owns and finalizes its Fx subscription.
+ *
  * @example
  * ```ts
  * import { Effect, Option } from "effect"
@@ -927,11 +1676,52 @@ export const filterMap = dual(2, function filterMap(versioned, f) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Optional queries
  */
 export const compact = function compact(versioned) {
     return new FilteredImpl(versioned, Effect.succeed);
 };
+/**
+ * Returns a `Computed` that yields the value inside the `Option`, or the fallback when `None`.
+ * Works with `Computed<Option<A>>` (e.g. from `fromOption` / `fromNullable`) and with `Filtered<A>`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Returns a `Computed` that yields the value inside the `Option`, or the fallback when `None`.
+ * Works with `Computed<Option<A>>` (e.g. from `fromOption` / `fromNullable`) and with
+ * `Filtered<A>`. Current reads and pushed versions use the same derivation, preventing snapshot
+ * and subscription behavior from diverging.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Computed never fails for absence: `None` or an absent Filtered value invokes
+ * `fallback`. It preserves only the input's declared `E` and `R`; the pure fallback adds no failure,
+ * service, subscription, or retained value.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import * as RefSubject from "@typed/fx/RefSubject"
+ *
+ * const program = Effect.gen(function* () {
+ *   const ref = yield* RefSubject.fromOption(Option.some(42))
+ *   const withDefault = RefSubject.getOrElse(ref, () => 0)
+ *   expect(yield* withDefault).toBe(42)
+ *
+ *   const empty = yield* RefSubject.fromNullable(null)
+ *   const fallback = RefSubject.getOrElse(empty, () => 99)
+ *   expect(yield* fallback).toBe(99)
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Optional queries
+ */
+export const getOrElse = dual(2, function getOrElse(ref, fallback) {
+    const computed = FilteredTypeId in ref ? ref.asComputed() : ref;
+    return map(computed, (opt) => Option.getOrElse(opt, fallback));
+});
 class RefSubjectSimpleTransform extends YieldableFx {
     [ComputedTypeId] = ComputedTypeId;
     [RefSubjectTypeId] = RefSubjectTypeId;
@@ -956,7 +1746,7 @@ class RefSubjectSimpleTransform extends YieldableFx {
         return this._fx.run(sink);
     }
     toEffect() {
-        return this.transformEffect(this.ref.asEffect());
+        return this.transformEffect(this.ref);
     }
     updates(run) {
         return this.ref.updates(run);
@@ -968,6 +1758,25 @@ class RefSubjectSimpleTransform extends YieldableFx {
         return this.ref.onSuccess(value);
     }
 }
+/**
+ * Limits which pushed versions a RefSubject view observes without changing its state.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Applies `skip` and `take` only to the Fx observation channel. Current reads still sample the
+ * underlying RefSubject directly, and writes still use its original serialized update boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Creating the view starts nothing and retains no value. Each observation uses its Scope and ends
+ * after `take` selected pushes; ending that observation does not interrupt or delete the source.
+ * Version, interruption, subscriber count, reads, failures, services, and writes delegate to the
+ * source RefSubject.
+ *
+ * @since 1.18.0
+ * @category Observation policy
+ */
 export const slice = dual(3, function slice(ref, skip, take) {
     return new RefSubjectSimpleTransform(ref, (_) => fxSlice(_, { skip, take }), identity);
 });
@@ -995,7 +1804,7 @@ class RefSubjectTransform extends YieldableFx {
         return this._fx.run(sink);
     }
     toEffect() {
-        return Effect.map(this.ref.asEffect(), this.toB);
+        return Effect.map(this.ref, this.toB);
     }
     updates(run) {
         return this.ref.updates((innerRef) => {
@@ -1017,6 +1826,17 @@ class RefSubjectTransform extends YieldableFx {
 /**
  * Transforms a `RefSubject` invariantly using bidirectional mapping functions.
  *
+ * @remarks
+ * ## Why
+ *
+ * Creates a bidirectional lens over state: reads map outward and writes map back to the original
+ * RefSubject without allocating a second store.
+ *
+ * ## Ownership and lifetime
+ *
+ * The derived ref owns no independent state or subscription. It follows the source lifetime and
+ * routes writes through the source's synchronized update boundary.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -1045,7 +1865,7 @@ class RefSubjectTransform extends YieldableFx {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Writable views
  */
 export const transform = dual(3, function transform(ref, toB, toA) {
     return new RefSubjectTransform(ref, toB, toA);
@@ -1077,6 +1897,17 @@ function getRefKind(refs) {
 /**
  * Combines multiple `RefSubject`, `Computed`, or `Filtered` instances into a single struct.
  *
+ * @remarks
+ * ## Why
+ *
+ * Combines several refs into one state value while preserving whether the result is writable,
+ * computed, or filtered from its inputs.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration performs no acquisition and retains no resources. Implementations preserve
+ * source errors, services, and lifetime.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -1107,7 +1938,7 @@ function getRefKind(refs) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category State composition
  */
 export function struct(refs) {
     const kind = getRefKind(Object.values(refs));
@@ -1123,6 +1954,17 @@ export function struct(refs) {
 /**
  * Combines multiple `RefSubject`, `Computed`, or `Filtered` instances into a single tuple.
  *
+ * @remarks
+ * ## Why
+ *
+ * Combines several refs into one state value while preserving whether the result is writable,
+ * computed, or filtered from its inputs.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration performs no acquisition and retains no resources. Implementations preserve
+ * source errors, services, and lifetime.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -1149,7 +1991,7 @@ export function struct(refs) {
  * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category State composition
  */
 export function tuple(refs) {
     const kind = getRefKind(refs);
@@ -1166,6 +2008,38 @@ function makeTupleRef(refs) {
     return new RefSubjectTuple(refs);
 }
 const UNBOUNDED = { concurrency: "unbounded" };
+const sampleRefSubject = (ref) => 
+// @effect-diagnostics-next-line unnecessaryEffectGen:off
+Effect.gen(function* () {
+    return yield* ref;
+});
+function versionedInContext(make) {
+    // Automatic composites share both pushed sessions and in-flight reads only within one Context.
+    const contexts = new WeakMap();
+    const current = Effect.map(Effect.context(), (context) => {
+        let versioned = contexts.get(context);
+        if (!versioned) {
+            versioned = make();
+            contexts.set(context, versioned);
+        }
+        return versioned;
+    });
+    return new (class extends YieldableFx {
+        version = Effect.flatMap(current, (versioned) => versioned.version);
+        interrupt = Effect.flatMap(current, (versioned) => versioned.interrupt);
+        run(sink) {
+            return Effect.flatMap(current, (versioned) => versioned.run(sink));
+        }
+        toEffect() {
+            return Effect.flatMap(current, identity);
+        }
+    })();
+}
+function makeCompositeVersioned(refs, current) {
+    const version = Effect.map(Effect.all(refs.map((ref) => ref.version), UNBOUNDED), (versions) => versions.reduce(sum, 0));
+    const changes = skipRepeats(fxMapEffect(fxMergeAll(...refs), () => current));
+    return versionedInContext(() => Versioned.hold(Versioned.make(version, changes, current)));
+}
 class RefSubjectTuple extends YieldableFx {
     [ComputedTypeId] = ComputedTypeId;
     [RefSubjectTypeId] = RefSubjectTypeId;
@@ -1178,12 +2052,14 @@ class RefSubjectTuple extends YieldableFx {
     constructor(refs) {
         super();
         this.refs = refs;
-        this.versioned = Versioned.hold(Versioned.tuple(refs));
+        this.versioned = (refs.length > 0 && getTupleTransactionAccess(refs)
+            ? makeCompositeVersioned(refs, Effect.all(refs.map(sampleRefSubject), UNBOUNDED))
+            : versionedInContext(() => Versioned.hold(Versioned.tuple(refs))));
         this.version = this.versioned.version;
         this.interrupt = Effect.all(refs.map((r) => r.interrupt), UNBOUNDED);
         this.subscriberCount = Effect.map(Effect.all(refs.map((r) => r.subscriberCount), UNBOUNDED), Array.reduce(0, sum));
         this.getSetDelete = {
-            get: this.versioned.asEffect(),
+            get: this.versioned,
             set: (a) => Effect.all(refs.map((r, i) => set(r, a[i])), UNBOUNDED),
             delete: Effect.map(Effect.all(refs.map((r) => reset(r)), UNBOUNDED), Option.all),
         };
@@ -1195,10 +2071,15 @@ class RefSubjectTuple extends YieldableFx {
         return this.versioned.run(sink);
     }
     toEffect() {
-        return this.versioned.asEffect();
+        return this.versioned;
     }
     updates(run) {
-        return run(this.getSetDelete);
+        const accessEffect = getTransactionAccess(this);
+        return accessEffect
+            ? Effect.flatMap(accessEffect, (transactionAccess) => Option.isSome(transactionAccess)
+                ? runTransaction(transactionAccess.value, run)
+                : Effect.suspend(() => run(this.getSetDelete)))
+            : Effect.suspend(() => run(this.getSetDelete));
     }
     onFailure(cause) {
         return Effect.all(this.refs.map((ref) => ref.onFailure(cause)));
@@ -1208,10 +2089,10 @@ class RefSubjectTuple extends YieldableFx {
     }
 }
 function makeTupleComputed(refs) {
-    return new ComputedImpl(Versioned.tuple(refs), Effect.succeed);
+    return new ComputedImpl(versionedInContext(() => Versioned.tuple(refs)), Effect.succeed);
 }
 function makeTupleFiltered(refs) {
-    return new FilteredImpl(Versioned.tuple(refs), Effect.succeedSome);
+    return new FilteredImpl(versionedInContext(() => Versioned.tuple(refs)), Effect.succeedSome);
 }
 function makeStructRef(refs) {
     return new RefSubjectStruct(refs);
@@ -1228,12 +2109,16 @@ class RefSubjectStruct extends YieldableFx {
     constructor(refs) {
         super();
         this.refs = refs;
-        this.versioned = Versioned.hold(Versioned.struct(refs));
+        const keys = Object.keys(refs);
+        const current = Effect.map(Effect.all(keys.map((key) => sampleRefSubject(refs[key])), UNBOUNDED), (values) => Object.fromEntries(keys.map((key, index) => [key, values[index]])));
+        this.versioned = (keys.length > 0 && getStructTransactionAccess(refs)
+            ? makeCompositeVersioned(Object.values(refs), current)
+            : versionedInContext(() => Versioned.hold(Versioned.struct(refs))));
         this.version = this.versioned.version;
         this.interrupt = Effect.all(Object.values(refs).map((r) => r.interrupt), UNBOUNDED);
         this.subscriberCount = Effect.map(Effect.all(Object.values(refs).map((r) => r.subscriberCount), UNBOUNDED), Array.reduce(0, sum));
         this.getSetDelete = {
-            get: this.versioned.asEffect(),
+            get: this.versioned,
             set: (a) => Effect.all(Object.keys(refs).map((k) => set(refs[k], a[k])), UNBOUNDED),
             delete: Effect.map(Effect.all(Object.values(refs).map((r) => reset(r)), UNBOUNDED), Option.all),
         };
@@ -1245,10 +2130,15 @@ class RefSubjectStruct extends YieldableFx {
         return this.versioned.run(sink);
     }
     toEffect() {
-        return this.versioned.asEffect();
+        return this.versioned;
     }
     updates(run) {
-        return run(this.getSetDelete);
+        const accessEffect = getTransactionAccess(this);
+        return accessEffect
+            ? Effect.flatMap(accessEffect, (transactionAccess) => Option.isSome(transactionAccess)
+                ? runTransaction(transactionAccess.value, run)
+                : Effect.suspend(() => run(this.getSetDelete)))
+            : Effect.suspend(() => run(this.getSetDelete));
     }
     onFailure(cause) {
         return Effect.all(Object.values(this.refs).map((ref) => ref.onFailure(cause)));
@@ -1258,11 +2148,29 @@ class RefSubjectStruct extends YieldableFx {
     }
 }
 function makeStructComputed(refs) {
-    return new ComputedImpl(Versioned.struct(refs), Effect.succeed);
+    return new ComputedImpl(versionedInContext(() => Versioned.struct(refs)), Effect.succeed);
 }
 function makeStructFiltered(refs) {
-    return new FilteredImpl(Versioned.struct(refs), Effect.succeedSome);
+    return new FilteredImpl(versionedInContext(() => Versioned.struct(refs)), Effect.succeedSome);
 }
+/**
+ * Lifts an Effect-provided Computed into a Computed facade.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Defers service lookup until each version read, current read, interruption, or Fx observation, so
+ * callers can compose a Context-provided Computed without manually flat-mapping the service Effect.
+ *
+ * ## Ownership and lifetime
+ *
+ * The facade caches neither the resolved Computed nor its value. Each operation runs the supplied
+ * Effect, then delegates to the resolved Computed. Service requirements combine as `R | R2`, source
+ * failures remain `E`, and the observing Scope owns the delegated subscription.
+ *
+ * @since 1.18.0
+ * @category Services
+ */
 export function computedFromService(effect) {
     return new ComputedFromService(effect);
 }
@@ -1281,9 +2189,26 @@ class ComputedFromService extends YieldableFx {
         return Effect.flatMap(this.effect, (c) => c.run(sink));
     }
     toEffect() {
-        return Effect.flatMap(this.effect, (c) => c.asEffect());
+        return Effect.flatMap(this.effect, (c) => c);
     }
 }
+/**
+ * Defers retrieval of a Filtered value from Effect Context while preserving Filtered behavior.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Lets a service-provided Filtered participate directly in Effect reads and Fx observation without
+ * manually flat-mapping the service tag at every use.
+ *
+ * ## Ownership and lifetime
+ *
+ * The filtered from service view retains no independent value. Its Effect read fails with NoSuchElement
+ * while absent; the observing Scope owns and finalizes its Fx subscription.
+ *
+ * @since 1.18.0
+ * @category Services
+ */
 export function filteredFromService(effect) {
     return new FilteredFromService(effect);
 }
@@ -1302,9 +2227,10 @@ class FilteredFromService extends YieldableFx {
         return Effect.flatMap(this.effect, (c) => c.run(sink));
     }
     toEffect() {
-        return Effect.flatMap(this.effect, (c) => c.asEffect());
+        return Effect.flatMap(this.effect, (c) => c);
     }
     asComputed() {
         return computedFromService(Effect.map(this.effect, (c) => c.asComputed()));
     }
 }
+export * from "./Hydration.js";