effect 4.0.0-beta.67 → 4.0.0-beta.68

package/src/unstable/reactivity/Atom.ts

@@ -58,7 +58,7 @@ import * as Reactivity from "./Reactivity.ts"
 /**
  * Type-level identifier used to recognize `Atom` values.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/reactivity/Atom"
@@ -66,7 +66,7 @@ export type TypeId = "~effect/reactivity/Atom"
 /**
  * Runtime identifier attached to `Atom` values and used by `isAtom`.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/reactivity/Atom"
@@ -91,7 +91,7 @@ export interface Atom<A> extends Pipeable, Inspectable.Inspectable {
 /**
  * Returns `true` when a value is an `Atom`.
  *
- * @category Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isAtom = (u: unknown): u is Atom<any> => hasProperty(u, TypeId)
@@ -99,6 +99,7 @@ export const isAtom = (u: unknown): u is Atom<any> => hasProperty(u, TypeId)
 /**
  * Extracts the value type produced by an `Atom`.
  *
+ * @category utility types
  * @since 4.0.0
  */
 export type Type<T extends Atom<any>> = T extends Atom<infer A> ? A : never
@@ -106,6 +107,7 @@ export type Type<T extends Atom<any>> = T extends Atom<infer A> ? A : never
 /**
  * Extracts the success value type from an atom whose value is an `AsyncResult`.
  *
+ * @category utility types
  * @since 4.0.0
  */
 export type Success<T extends Atom<any>> = T extends Atom<AsyncResult.AsyncResult<infer A, infer _>> ? A : never
@@ -113,6 +115,7 @@ export type Success<T extends Atom<any>> = T extends Atom<AsyncResult.AsyncResul
 /**
  * Extracts the item type from an atom whose value is a `PullResult`.
  *
+ * @category utility types
  * @since 4.0.0
  */
 export type PullSuccess<T extends Atom<any>> = T extends Atom<PullResult<infer A, infer _>> ? A : never
@@ -120,6 +123,7 @@ export type PullSuccess<T extends Atom<any>> = T extends Atom<PullResult<infer A
 /**
  * Extracts the failure error type from an atom whose value is an `AsyncResult`.
  *
+ * @category utility types
  * @since 4.0.0
  */
 export type Failure<T extends Atom<any>> = T extends Atom<AsyncResult.AsyncResult<infer _, infer E>> ? E : never
@@ -127,6 +131,7 @@ export type Failure<T extends Atom<any>> = T extends Atom<AsyncResult.AsyncResul
 /**
  * Returns an atom type without serializable metadata, preserving `Writable` read and write types when the input atom is writable.
  *
+ * @category utility types
  * @since 4.0.0
  */
 export type WithoutSerializable<T extends Atom<any>> = T extends Writable<infer R, infer W> ? Writable<R, W>
@@ -135,7 +140,7 @@ export type WithoutSerializable<T extends Atom<any>> = T extends Writable<infer
 /**
  * Runtime identifier attached to writable atoms and used by `isWritable`.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const WritableTypeId: WritableTypeId = "~effect/reactivity/Atom/Writable"
@@ -143,7 +148,7 @@ export const WritableTypeId: WritableTypeId = "~effect/reactivity/Atom/Writable"
 /**
  * Type-level identifier used to recognize writable atoms.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type WritableTypeId = "~effect/reactivity/Atom/Writable"
@@ -2644,7 +2649,7 @@ function updateSearchParams() {
  * The stream emits the atom's current value immediately and then emits subsequent
  * changes until the stream scope is closed.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toStream = <A>(self: Atom<A>): Stream.Stream<A, never, AtomRegistry> =>
@@ -2656,7 +2661,7 @@ export const toStream = <A>(self: Atom<A>): Stream.Stream<A, never, AtomRegistry
  * Initial results are skipped, successes are emitted as stream values, and
  * failures fail the stream with the result cause.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toStreamResult = <A, E>(self: Atom<AsyncResult.AsyncResult<A, E>>): Stream.Stream<A, E, AtomRegistry> =>
@@ -2665,7 +2670,7 @@ export const toStreamResult = <A, E>(self: Atom<AsyncResult.AsyncResult<A, E>>):
 /**
  * Reads an atom's current value from the `AtomRegistry` service.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const get = <A>(self: Atom<A>): Effect.Effect<A, never, AtomRegistry> =>
@@ -2675,7 +2680,7 @@ export const get = <A>(self: Atom<A>): Effect.Effect<A, never, AtomRegistry> =>
  * Reads a writable atom, computes a return value and next write value, writes the
  * next value, and returns the computed result.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const modify: {
@@ -2683,7 +2688,7 @@ export const modify: {
    * Reads a writable atom, computes a return value and next write value, writes the
    * next value, and returns the computed result.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <R, W, A>(f: (_: R) => [returnValue: A, nextValue: W]): (self: Writable<R, W>) => Effect.Effect<A, never, AtomRegistry>
@@ -2691,7 +2696,7 @@ export const modify: {
    * Reads a writable atom, computes a return value and next write value, writes the
    * next value, and returns the computed result.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <R, W, A>(self: Writable<R, W>, f: (_: R) => [returnValue: A, nextValue: W]): Effect.Effect<A, never, AtomRegistry>
@@ -2704,21 +2709,21 @@ export const modify: {
 /**
  * Writes a value to a writable atom through the `AtomRegistry` service.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const set: {
   /**
    * Writes a value to a writable atom through the `AtomRegistry` service.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <W>(value: W): <R>(self: Writable<R, W>) => Effect.Effect<void, never, AtomRegistry>
   /**
    * Writes a value to a writable atom through the `AtomRegistry` service.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <R, W>(self: Writable<R, W>, value: W): Effect.Effect<void, never, AtomRegistry>
@@ -2732,7 +2737,7 @@ export const set: {
  * Updates a writable atom by reading its current value from the registry and
  * writing the value returned by the update function.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const update: {
@@ -2740,7 +2745,7 @@ export const update: {
    * Updates a writable atom by reading its current value from the registry and
    * writing the value returned by the update function.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <R, W>(f: (_: R) => W): (self: Writable<R, W>) => Effect.Effect<void, never, AtomRegistry>
@@ -2748,7 +2753,7 @@ export const update: {
    * Updates a writable atom by reading its current value from the registry and
    * writing the value returned by the update function.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <R, W>(self: Writable<R, W>, f: (_: R) => W): Effect.Effect<void, never, AtomRegistry>
@@ -2765,7 +2770,7 @@ export const update: {
  * when `suspendOnWaiting` is enabled. Successes succeed with the value and
  * failures fail with the result cause.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const getResult = <A, E>(
@@ -2776,7 +2781,7 @@ export const getResult = <A, E>(
 /**
  * Requests a refresh of an atom through the `AtomRegistry` service.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const refresh = <A>(self: Atom<A>): Effect.Effect<void, never, AtomRegistry> =>
@@ -2788,7 +2793,7 @@ export const refresh = <A>(self: Atom<A>): Effect.Effect<void, never, AtomRegist
  * Mounting keeps the atom subscribed with a no-op listener until the scope
  * finalizer releases it.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const mount = <A>(self: Atom<A>): Effect.Effect<void, never, AtomRegistry | Scope.Scope> =>

package/src/unstable/reactivity/AtomHttpApi.ts

@@ -54,7 +54,7 @@ import * as Reactivity from "./Reactivity.ts"
  * It exposes the generated HTTP API client, an atom runtime, mutation helpers that
  * return `AtomResultFn`s, and query helpers that return atoms of endpoint results.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface AtomHttpApiClient<Self, Id extends string, Groups extends HttpApiGroup.Any>
@@ -178,7 +178,7 @@ declare global {
  * response transforms, base URL, and runtime factory used by the query and
  * mutation helpers.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const Service = <Self>() =>

package/src/unstable/reactivity/AtomRef.ts

@@ -24,7 +24,7 @@ import * as Hash from "../../Hash.ts"
 /**
  * The literal type used to identify `AtomRef` values.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/reactivity/AtomRef"
@@ -32,7 +32,7 @@ export type TypeId = "~effect/reactivity/AtomRef"
 /**
  * The runtime type id used to identify `AtomRef` values.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/reactivity/AtomRef"

package/src/unstable/reactivity/AtomRegistry.ts

@@ -39,7 +39,7 @@ import type * as Atom from "./Atom.ts"
 /**
  * The literal type used to identify `AtomRegistry` services and values.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/reactivity/AtomRegistry"
@@ -47,7 +47,7 @@ export type TypeId = "~effect/reactivity/AtomRegistry"
 /**
  * The runtime type id used to identify `AtomRegistry` services and values.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/reactivity/AtomRegistry"
@@ -148,7 +148,7 @@ export const AtomRegistry = Context.Service<AtomRegistry>(TypeId)
  *
  * The registry is disposed when the layer scope is finalized.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerOptions = (options?: {
@@ -173,7 +173,7 @@ export const layerOptions = (options?: {
 /**
  * The default layer that provides a fresh `AtomRegistry`.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layer: Layer.Layer<AtomRegistry> = layerOptions()
@@ -188,7 +188,7 @@ export const layer: Layer.Layer<AtomRegistry> = layerOptions()
  * The stream emits the current value immediately, emits subsequent changes, and
  * unsubscribes from the registry when the stream scope closes.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toStream: {
@@ -202,7 +202,7 @@ export const toStream: {
    * The stream emits the current value immediately, emits subsequent changes, and
    * unsubscribes from the registry when the stream scope closes.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <A>(atom: Atom.Atom<A>): (self: AtomRegistry) => Stream.Stream<A>
@@ -216,7 +216,7 @@ export const toStream: {
    * The stream emits the current value immediately, emits subsequent changes, and
    * unsubscribes from the registry when the stream scope closes.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <A>(self: AtomRegistry, atom: Atom.Atom<A>): Stream.Stream<A>
@@ -233,7 +233,7 @@ export const toStream: {
      * The stream emits the current value immediately, emits subsequent changes, and
      * unsubscribes from the registry when the stream scope closes.
      *
-     * @category Conversions
+     * @category converting
      * @since 4.0.0
      */
     A>((queue) =>
@@ -255,7 +255,7 @@ export const toStream: {
  * Initial results are skipped, failures fail the stream with their cause, and
  * duplicate stream values are dropped with `Stream.changes`.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toStreamResult: {
@@ -266,7 +266,7 @@ export const toStreamResult: {
    * Initial results are skipped, failures fail the stream with their cause, and
    * duplicate stream values are dropped with `Stream.changes`.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <A, E>(atom: Atom.Atom<Result.AsyncResult<A, E>>): (self: AtomRegistry) => Stream.Stream<A, E>
@@ -277,7 +277,7 @@ export const toStreamResult: {
    * Initial results are skipped, failures fail the stream with their cause, and
    * duplicate stream values are dropped with `Stream.changes`.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <A, E>(self: AtomRegistry, atom: Atom.Atom<Result.AsyncResult<A, E>>): Stream.Stream<A, E>
@@ -299,7 +299,7 @@ export const toStreamResult: {
  * The effect waits for the result to leave `Initial`, and also waits through
  * waiting results when `suspendOnWaiting` is enabled.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const getResult: {
@@ -309,7 +309,7 @@ export const getResult: {
    * The effect waits for the result to leave `Initial`, and also waits through
    * waiting results when `suspendOnWaiting` is enabled.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <A, E>(
@@ -324,7 +324,7 @@ export const getResult: {
    * The effect waits for the result to leave `Initial`, and also waits through
    * waiting results when `suspendOnWaiting` is enabled.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <A, E>(
@@ -362,7 +362,7 @@ export const getResult: {
  * The atom is subscribed with a no-op listener and the subscription is released
  * when the scope finalizer runs.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const mount: {
@@ -372,7 +372,7 @@ export const mount: {
    * The atom is subscribed with a no-op listener and the subscription is released
    * when the scope finalizer runs.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <A>(atom: Atom.Atom<A>): (self: AtomRegistry) => Effect.Effect<void, never, Scope.Scope>
@@ -382,7 +382,7 @@ export const mount: {
    * The atom is subscribed with a no-op listener and the subscription is released
    * when the scope finalizer runs.
    *
-   * @category Conversions
+   * @category converting
    * @since 4.0.0
    */
   <A>(self: AtomRegistry, atom: Atom.Atom<A>): Effect.Effect<void, never, Scope.Scope>

package/src/unstable/reactivity/AtomRpc.ts

@@ -50,7 +50,7 @@ import * as Reactivity from "./Reactivity.ts"
  * `AtomResultFn`s, and query helpers that return atoms or pull atoms for RPC
  * results.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface AtomRpcClient<Self, Id extends string, Rpcs extends Rpc.Any> extends
@@ -137,7 +137,7 @@ declare global {
  * generation, optional custom client effect, and runtime factory used by the query
  * and mutation helpers.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const Service = <Self>() =>

package/src/unstable/reactivity/Reactivity.ts

@@ -17,9 +17,8 @@
  * store them. Registrations are tied to the surrounding scope, failures from a
  * query fail the queue or stream, and invalidations that arrive while a query is
  * already running schedule a single follow-up run. Use stable key values, be
- * aware that the default layer is process-local, and wrap related work in
- * {@link Reactivity.withBatch} when many invalidations should be coalesced until
- * the batch exits.
+ * aware that the default layer is process-local, and use the {@link Reactivity}
+ * service when many invalidations should be coalesced until the batch exits.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/index.ts

@@ -5,41 +5,208 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * The `AsyncResult` module models the state of an asynchronous value inside the
+ * reactivity APIs. It represents whether a computation has not produced a
+ * result yet, has succeeded, or has failed, while keeping `waiting` as a
+ * separate flag for first loads, refreshes, retries, and other in-flight work.
+ *
+ * This is useful for atoms and UI integrations that need to render async
+ * queries, background refreshes, optimistic transitions, stream pulls, or RPC
+ * and HTTP calls without losing track of the current value. `Success` contains
+ * the latest value and timestamp, and `Failure` contains a `Cause` plus an
+ * optional `previousSuccess` so callers can keep showing stale data after a
+ * refresh fails.
+ *
+ * Treat `waiting` as an overlay rather than a fourth state: an `Initial` result
+ * can be waiting with no value, and a `Success` or `Failure` can also be waiting
+ * while a newer computation is running. Accessors such as `value` and
+ * `getOrElse` may return the previous success stored in a failure, so inspect
+ * `cause` or `error` when the difference between a current success and stale
+ * data matters. Matchers such as `matchWithWaiting` prioritize the waiting flag,
+ * while `match` and `matchWithError` expose the underlying state.
+ *
  * @since 4.0.0
  */
 export * as AsyncResult from "./AsyncResult.ts"
 
 /**
+ * The `Atom` module defines reactive values and the helpers for constructing,
+ * composing, running, and persisting them with an `AtomRegistry`. Atoms are
+ * small read functions whose regular `get` reads form a dependency graph, so
+ * derived values are cached by the registry and invalidated when their
+ * dependencies, writable state, refresh hooks, or subscriptions change.
+ *
+ * Use atoms for application and UI state, derived data, `Effect` or `Stream`
+ * queries exposed as `AsyncResult`, writable function atoms for commands,
+ * subscription refs, pull-based streams, optimistic updates, URL search
+ * parameters, `KeyValueStore` entries, and serializable or server-specific
+ * hydration.
+ *
+ * The cache belongs to the registry, not the atom object: the same atom can have
+ * different values in different registries, and serializable atoms are keyed by
+ * their serialization key. Stable atom identity matters for dependency tracking
+ * and cache reuse, so use `family` for parameterized atoms. Unobserved atoms are
+ * disposed unless kept alive or retained by an idle TTL, which can cause derived
+ * state, effects, streams, and finalizers to be rebuilt later. Runtime-backed
+ * atoms run effects and streams with the registry scheduler, scope, and
+ * `AtomRuntime` layer context; `runtime.withReactivity` only refreshes after
+ * explicit `Reactivity` invalidations, while one-shot reads such as `once` do
+ * not create dependency edges.
+ *
  * @since 4.0.0
  */
 export * as Atom from "./Atom.ts"
 
 /**
+ * The `AtomHttpApi` module adapts typed `HttpApi` clients to the unstable atom
+ * reactivity runtime. Use it to define a `Context.Service` whose generated HTTP
+ * API client is available directly and whose endpoints can also be invoked as
+ * atoms: `query` creates an atom of `AsyncResult` for reads, while `mutation`
+ * creates an `AtomResultFn` for writes.
+ *
+ * It is intended for applications that want server state to participate in atom
+ * caching, invalidation, and hydration. Queries can be associated with
+ * `reactivityKeys` so they refresh when those keys are invalidated, mutations can
+ * invalidate the same keys after the request succeeds, and `timeToLive` controls
+ * whether idle query atoms expire, stay alive for a duration, or are kept alive.
+ *
+ * Serialization is schema-based and intentionally limited to decoded values.
+ * Mutation atoms are serializable only in `"decoded-only"` mode, while query
+ * atoms are serializable only in `"decoded-only"` mode when a stable
+ * `serializationKey` is supplied. Choose serialization keys that uniquely
+ * identify the endpoint request, keep reactivity keys stable across client and
+ * server registries during hydration, and avoid serializing response modes that
+ * expose raw `HttpClientResponse` values.
+ *
+ * The service wraps `HttpApiClient.make`, so the same `HttpApi` definition,
+ * schemas, base URL, middleware services, and HTTP client layer must be available
+ * wherever the atom runtime is constructed. Use `transformClient` and
+ * `transformResponse` for cross-cutting client behavior, and remember that
+ * schema or low-level HTTP client failures are raised as defects while endpoint
+ * and middleware failures remain typed errors.
+ *
  * @since 4.0.0
  */
 export * as AtomHttpApi from "./AtomHttpApi.ts"
 
 /**
+ * Mutable reactive references for local, in-memory state that should be read,
+ * updated, and observed without going through an `AtomRegistry`.
+ *
+ * `AtomRef` is useful for small state models, form-like state, and collections
+ * of item references where callers need direct mutation methods together with
+ * subscriptions. A ref exposes its current `value`, notifies subscribers after
+ * `set` or `update`, can derive read-only views with `map`, and can focus on
+ * nested object or array properties with `prop`.
+ *
+ * Notifications are equality-aware: setting a value that is `Equal.equals` to
+ * the current value is ignored, and mapped or property subscriptions only emit
+ * when their derived value changes. Mutate state through `set`, `update`, or a
+ * property ref so subscribers are notified; direct mutation of the stored value
+ * does not notify listeners. Collection subscribers are notified when items are
+ * inserted, removed, or when an item ref changes, while `toArray` returns the
+ * current raw item values.
+ *
  * @since 4.0.0
  */
 export * as AtomRef from "./AtomRef.ts"
 
 /**
+ * The `AtomRegistry` module provides the runtime cache used by reactivity
+ * atoms. A registry owns the node graph for a group of atoms, stores their
+ * current values, records parent/child dependencies while atoms are read, and
+ * coordinates writes, refreshes, stream conversions, and node disposal.
+ *
+ * Create a registry directly with {@link make} or provide it with {@link layer}
+ * or {@link layerOptions} when a UI root, request, test, or other Effect scope
+ * needs its own atom state. The same atom can have different cached values in
+ * different registries, while serializable atoms are keyed by their
+ * serialization key so preloaded values can hydrate a node before its first
+ * read.
+ *
+ * Subscriptions and {@link mount} keep nodes alive and must be released when
+ * the consumer is done; scoped helpers install finalizers for this. Unobserved
+ * non-`keepAlive` atoms may be removed immediately or after their `idleTTL` (or
+ * the registry `defaultIdleTTL`), which means later reads can rebuild derived
+ * state. Disposing a registry clears its cache and makes future atom access an
+ * error.
+ *
  * @since 4.0.0
  */
 export * as AtomRegistry from "./AtomRegistry.ts"
 
 /**
+ * The `AtomRpc` module connects typed RPC clients to the atom reactivity
+ * runtime. It builds a `Context.Service` that exposes the flattened
+ * `RpcClient`, an `AtomRuntime`, mutation helpers, and query helpers for every
+ * RPC in an `RpcGroup`.
+ *
+ * Use it when remote read models should be represented as atoms, mutations
+ * should refresh affected reads through `Reactivity` keys, or non-streaming
+ * query results need serialization metadata for hydration. The RPC `protocol`
+ * layer supplies the transport, and may be static or derived from the current
+ * atom context, so request headers, transport dependencies, and client
+ * middleware remain part of the normal Effect environment.
+ *
+ * Non-streaming queries produce atoms of `AsyncResult` values. Supplying a
+ * `serializationKey` marks those query atoms as serializable using codecs
+ * derived from the RPC success schema and the combined RPC, middleware, and
+ * client error schemas; choose stable, unique keys when dehydrating. Streaming
+ * RPCs produce writable pull atoms instead, so callers advance the stream by
+ * writing to the atom and should not expect serialization metadata. Query family
+ * caching includes the payload, normalized headers, reactivity keys, TTL, and
+ * serialization key, so use stable values for those inputs when atom identity
+ * matters.
+ *
  * @since 4.0.0
  */
 export * as AtomRpc from "./AtomRpc.ts"
 
 /**
+ * Utilities for moving serializable reactivity state between atom registries.
+ *
+ * `dehydrate` snapshots atoms marked with `Atom.serializable` from an
+ * `AtomRegistry`, preserving their serialization keys, encoded values, and
+ * dehydration time so another registry can preload the same state with `hydrate`.
+ * This is useful for server rendering, browser bootstrapping, route transitions,
+ * and other handoffs where a registry should start from values that were already
+ * computed elsewhere.
+ *
+ * Only serializable atoms are included, and the receiving registry needs atoms
+ * with matching stable keys and compatible schemas. Values crossing a
+ * client/server boundary should be the encoded JSON-safe values produced by the
+ * atom codecs. The optional `resultPromise` used for `AsyncResult.Initial`
+ * handoffs is a live JavaScript promise, so it cannot be sent through JSON and
+ * should be omitted or replaced by an application-level streaming protocol when
+ * dehydrated state leaves the current runtime.
+ *
  * @since 4.0.0
  */
 export * as Hydration from "./Hydration.ts"
 
 /**
+ * The `Reactivity` module provides an in-memory service for connecting writes to
+ * dependent reads through explicit invalidation keys. It is useful for keeping
+ * query results, UI subscriptions, read models, or other derived views fresh
+ * after mutations without coupling the writer to every consumer that should
+ * rerun.
+ *
+ * Reads are modeled with {@link query} and {@link stream}: the effect runs once
+ * immediately and then runs again whenever one of its keys is invalidated.
+ * Writes can use {@link mutation} to invalidate keys only after the wrapped
+ * effect succeeds, or call {@link invalidate} directly. Keys may be supplied as
+ * a flat collection or as a record of namespaces with ids, which lets callers
+ * invalidate both broad groups and individual records.
+ *
+ * The service tracks handlers by hashed keys and does not cache values by
+ * itself; consumers receive fresh queue or stream emissions and decide how to
+ * store them. Registrations are tied to the surrounding scope, failures from a
+ * query fail the queue or stream, and invalidations that arrive while a query is
+ * already running schedule a single follow-up run. Use stable key values, be
+ * aware that the default layer is process-local, and wrap related work in
+ * {@link Reactivity.withBatch} when many invalidations should be coalesced until
+ * the batch exits.
+ *
  * @since 4.0.0
  */
 export * as Reactivity from "./Reactivity.ts"

package/src/unstable/rpc/Rpc.ts

@@ -1047,7 +1047,6 @@ export interface Custom {
 /**
  * Helper types for defining RPC custom constructors.
  *
- * @category Custom constructors
  * @since 4.0.0
  */
 export declare namespace Custom {

package/src/unstable/rpc/RpcClient.ts

@@ -80,7 +80,6 @@ export type RpcClient<Rpcs extends Rpc.Any, E = never> = Struct.Simplify<RpcClie
  * Type-level helpers for deriving RPC client call signatures from RPC
  * definitions.
  *
- * @category client
  * @since 4.0.0
  */
 export declare namespace RpcClient {

package/src/unstable/rpc/RpcClientError.ts

@@ -28,7 +28,7 @@ const TypeId = "~effect/rpc/RpcClientError"
  * Represents a client-side RPC defect, such as a protocol violation or
  * decoding failure, with a message and original cause.
  *
- * @category Errors
+ * @category errors
  * @since 4.0.0
  */
 export class RpcClientDefect extends Schema.ErrorClass<RpcClientDefect>("effect/rpc/RpcClientError/RpcClientDefect")({
@@ -41,7 +41,7 @@ export class RpcClientDefect extends Schema.ErrorClass<RpcClientDefect>("effect/
  * The public RPC client error type, wrapping worker, socket, HTTP client, and
  * client protocol defect failures.
  *
- * @category Errors
+ * @category errors
  * @since 4.0.0
  */
 export class RpcClientError extends Schema.ErrorClass<RpcClientError>(TypeId)({