effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/unstable/persistence/RateLimiter.ts

@@ -1,28 +1,12 @@
 /**
- * Persistent rate limiting for effects that need to coordinate token
- * consumption through a shared `RateLimiterStore`.
- *
- * The module exposes a `RateLimiter` service that can consume tokens for
- * string keys using either fixed-window counters or token-bucket state. It is
- * useful for protecting external APIs, enforcing per-user or per-tenant quotas,
- * throttling job workers, and coordinating limits across multiple fibers or
- * processes when they share the Redis-backed store. The helpers can fail fast
- * with `RateLimiterError`, return a delay to apply yourself, or wrap an effect
- * so it waits before continuing.
- *
- * Rate-limit keys and Redis prefixes are part of the persistence namespace, so
- * choose stable, collision-free values. The in-memory store is process-local
- * and is only coordinated inside one runtime, while the Redis store uses Lua
- * scripts for atomic updates under concurrent consumers. Time is measured with
- * the Effect `Clock`, windows are clamped to at least one millisecond, and
- * refill calculations use millisecond granularity.
- *
- * Fixed-window state is TTL-driven: rejected `fail` attempts do not extend the
- * current TTL, and Redis fixed-window keys expire automatically. Token-bucket
- * state keeps the remaining token count and last-refill time instead of using a
- * TTL, so high-cardinality dynamic keys may need an external cleanup or bounded
- * key strategy. With `onExceeded: "delay"`, overflow can be recorded so callers
- * should actually sleep for the returned delay, or use the provided accessors.
+ * Coordinates rate limits through shared persistent storage.
+ *
+ * The `RateLimiter` service consumes tokens for string keys using fixed-window
+ * counters or token-bucket state. It can protect external APIs, enforce quotas,
+ * or throttle workers across fibers and processes that share the same store.
+ * This module includes helpers that fail when a limit is exceeded, return the
+ * delay needed before continuing, or wrap an effect so it waits automatically.
+ * It also defines the store service and in-memory or Redis-backed store layers.
  *
  * @since 4.0.0
  */
@@ -630,11 +614,13 @@ export const makeStoreRedis = Effect.fnUntraced(function*(
     },
     tokenBucket(options) {
       const key = `${prefix}${options.key}`
+      const lastRefillKey = `${key}:refill`
       const refillMillis = Duration.toMillis(options.refillRate)
       return Effect.clockWith((clock) =>
         Effect.mapError(
           tokenBucket(
             key,
+            lastRefillKey,
             options.tokens,
             refillMillis,
             options.limit,
@@ -687,17 +673,18 @@ return { next, nextpttl }
 const tokenBucketScript = Redis.script(
   (
     key: string,
+    lastRefillKey: string,
     tokens: number,
     refillMillis: number,
     limit: number,
     now: number,
     overflow: 0 | 1
-  ) => [key, tokens, refillMillis, limit, now, overflow],
+  ) => [key, lastRefillKey, tokens, refillMillis, limit, now, overflow],
   {
-    numberOfKeys: 1,
+    numberOfKeys: 2,
     lua: `
 local key = KEYS[1]
-local last_refill_key = key .. ":refill"
+local last_refill_key = KEYS[2]
 local tokens = tonumber(ARGV[1])
 local refill_ms = tonumber(ARGV[2])
 local limit = tonumber(ARGV[3])
@@ -706,28 +693,26 @@ local overflow = ARGV[5] == "1"
 local current = tonumber(redis.call("GET", key))
 local last_refill = tonumber(redis.call("GET", last_refill_key))
 
-if not current then
-  current = limit
-  last_refill = now
-  redis.call("SET", key, current)
-  redis.call("SET", last_refill_key, last_refill)
-end
+if not current then current = limit end
+if not last_refill then last_refill = now end
 
 local elapsed = now - last_refill
 local refill_amount = math.floor(elapsed / refill_ms)
 if refill_amount > 0 then
   current = math.min(current + refill_amount, limit)
   last_refill = last_refill + (refill_amount * refill_ms)
-  redis.call("SET", last_refill_key, last_refill)
 end
 
 local next = current - tokens
-if next < 0 and not overflow then
-  redis.call("SET", key, current)
-  return next
+local stored = current
+if next >= 0 or overflow then
+  stored = next
 end
 
-redis.call("SET", key, next)
+local ttl = math.floor((limit - stored) * refill_ms)
+if ttl < 1 then ttl = 1 end
+redis.call("SET", key, stored, "PX", ttl)
+redis.call("SET", last_refill_key, last_refill, "PX", ttl)
 return next
 `
   }

package/src/unstable/persistence/Redis.ts

@@ -1,37 +1,11 @@
 /**
- * Redis service adapter for Effect persistence modules.
+ * Redis support shared by persistence modules.
  *
- * This module defines the low-level {@link Redis} service used by Redis-backed
- * persistence, persisted queues, and rate limiter stores. It adapts a Redis
- * client or pool into Effect through a raw `send` command function and cached
- * Lua script execution.
- *
- * **Mental model**
- *
- * The service does not create or own Redis connections. {@link make} wraps a
- * caller-provided command sender, while {@link script} describes a Lua script's
- * source, parameters, key count, and result type. The service loads scripts
- * with `SCRIPT LOAD`, caches the returned SHA, and runs them with `EVALSHA`
- * through `Redis.eval`.
- *
- * **Common tasks**
- *
- * - Wrap an existing Redis client by implementing `send`.
- * - Use `Redis.send` for ordinary Redis commands.
- * - Use {@link script} for typed Lua helpers shared by persistence stores.
- * - Map client or network failures into {@link RedisError} in the provided
- *   command sender.
- *
- * **Gotchas**
- *
- * Script parameters are stringified before execution. The script descriptor's
- * key count controls how Redis splits `KEYS` from `ARGV`. Higher-level stores
- * add key prefixes and store ids on top of this service, so those identifiers
- * must stay stable when persisted data is expected to survive deployments.
- *
- * **See also**
- *
- * {@link Redis}, {@link make}, {@link script}, {@link RedisError}.
+ * This module defines a `Redis` service that can send Redis commands and run
+ * Lua scripts. It does not create a Redis client itself; callers provide a
+ * `send` function from their client or connection pool. The module also
+ * provides helpers for describing Lua scripts, loading them once, and running
+ * them later by their cached Redis id.
  *
  * @since 4.0.0
  */
@@ -89,14 +63,22 @@ export const make = Effect.fnUntraced(function*(
   >(
     script: Script<Config>
   ) =>
-  (...params: Config["params"]): Effect.Effect<Config["result"], RedisError> =>
-    Effect.flatMap(Cache.get(scriptCache, script), (sha) =>
+  (...params: Config["params"]): Effect.Effect<Config["result"], RedisError> => {
+    const evalSha = (sha: string) =>
       options.send<Config["result"]>(
         "EVALSHA",
         sha,
         script.numberOfKeys(...params).toString(),
         ...script.params(...params).map((param) => String(param))
-      ))
+      )
+    return Cache.get(scriptCache, script).pipe(
+      Effect.flatMap(evalSha),
+      Effect.catchIf(
+        (error) => String(error.cause).includes("NOSCRIPT"),
+        () => Cache.refresh(scriptCache, script).pipe(Effect.flatMap(evalSha))
+      )
+    )
+  }
 
   return identity<Redis["Service"]>({
     send: options.send,

package/src/unstable/process/ChildProcess.ts

@@ -1,43 +1,11 @@
 /**
- * An Effect-native module for working with child processes.
+ * Describes child processes before they are started.
  *
- * This module uses an AST-based approach where commands are built first
- * using `make` and `pipeTo`, then executed using `spawn`.
- *
- * **Example** (Spawning and piping commands)
- *
- * ```ts
- * import { Effect, Stream } from "effect"
- * import { NodeServices } from "@effect/platform-node"
- * import { ChildProcess } from "effect/unstable/process"
- *
- * // Build a command
- * const command = ChildProcess.make`echo "hello world"`
- *
- * // Spawn and collect output
- * const program = Effect.gen(function*() {
- *   // You can `yield*` a command, which calls `ChildProcess.spawn`
- *   const handle = yield* command
- *   const chunks = yield* Stream.runCollect(handle.stdout)
- *   const exitCode = yield* handle.exitCode
- *   return { chunks, exitCode }
- * }).pipe(Effect.scoped, Effect.provide(NodeServices.layer))
- *
- * // With options
- * const withOptions = ChildProcess.make({ cwd: "/tmp" })`ls -la`
- *
- * // Piping commands
- * const pipeline = ChildProcess.make`cat package.json`.pipe(
- *   ChildProcess.pipeTo(ChildProcess.make`grep name`)
- * )
- *
- * // Spawn the pipeline
- * const pipelineProgram = Effect.gen(function*() {
- *   const handle = yield* pipeline
- *   const chunks = yield* Stream.runCollect(handle.stdout)
- *   return chunks
- * }).pipe(Effect.scoped, Effect.provide(NodeServices.layer))
- * ```
+ * A `Command` stores the executable, arguments, environment, standard streams,
+ * working directory, and other process options. Commands can also be piped
+ * together. A command is an `Effect`; running it asks the
+ * `ChildProcessSpawner` service to start the process and returns a
+ * `ChildProcessHandle`.
  *
  * @since 4.0.0
  */

package/src/unstable/process/ChildProcessSpawner.ts

@@ -1,20 +1,12 @@
 /**
- * Service contract and helpers for running child processes through Effect.
+ * Service boundary for starting and controlling child processes.
  *
- * This module defines the {@link ChildProcessSpawner} service used by child
- * process commands to start operating-system processes. A spawner turns a
- * command description into a {@link ChildProcessHandle}, which exposes scoped
- * lifecycle operations: write to stdin, stream stdout and stderr, wait for the
- * exit code, kill the process, inspect whether it is still running, and
- * temporarily unreference it from the parent process.
- *
- * Use this module when implementing a platform-specific process backend or
- * when code needs direct access to the process service. Most applications build
- * commands with the `ChildProcess` module; this service is the lower-level
- * execution boundary and also provides convenience methods for collecting exit
- * codes, strings, and output lines. The {@link make} constructor derives those
- * helpers from one primitive `spawn` implementation, so adapters only need to
- * supply process creation.
+ * `ChildProcessSpawner` is the service used by `ChildProcess` commands to start
+ * operating-system processes. A spawner turns a command description into a
+ * handle that can write to stdin, read stdout and stderr, wait for exit, kill
+ * the process, and manage whether the process keeps its parent alive. Platform
+ * backends implement this service, while most application code uses the higher
+ * level `ChildProcess` module.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AsyncResult.ts

@@ -1,44 +1,12 @@
 /**
- * State containers for asynchronous values used by the reactivity APIs.
+ * Represents observable state for asynchronous values.
  *
- * `AsyncResult` records the latest observable state of work that may still be
- * loading, refreshing, retrying, or recovering from failure. The value is one of
- * `Initial`, `Success`, or `Failure`, and every variant also carries a `waiting`
- * flag so callers can keep rendering the current state while newer work is in
- * flight.
- *
- * **Mental model**
- *
- * The variant answers "what do we know right now?", while `waiting` answers "is
- * newer work currently running?". A success contains the current value and its
- * timestamp. A failure contains a `Cause` and may also keep the previous
- * success, which lets UI and atom code show stale data while exposing the latest
- * failure for error displays and retry logic.
- *
- * **Common tasks**
- *
- * - Start with {@link initial}, {@link success}, {@link failure}, or
- *   {@link fail}
- * - Convert Effect exits with {@link fromExit} and
- *   {@link fromExitWithPrevious}
- * - Mark existing state as loading with {@link waiting} or
- *   {@link waitingFrom}
- * - Read values and failures with {@link value}, {@link cause}, {@link error},
- *   {@link getOrElse}, and {@link toExit}
- * - Transform and combine results with {@link map}, {@link flatMap}, and
- *   {@link all}
- * - Render all states with {@link match}, {@link matchWithWaiting}, or
- *   {@link builder}
- *
- * **Gotchas**
- *
- * - `waiting` is an overlay, not a fourth variant; any variant can be waiting.
- * - {@link value} and {@link getOrElse} can read the previous success stored in
- *   a failure, so inspect {@link cause} or {@link error} when stale data and a
- *   current success must be distinguished.
- * - {@link matchWithWaiting} handles waiting before variant-specific branches,
- *   while {@link match} and {@link matchWithError} expose the underlying
- *   variant first.
+ * `AsyncResult<A, E>` records whether asynchronous work has no value yet,
+ * succeeded with an `A`, or failed with an `E`. Every state also carries a
+ * `waiting` flag, so callers can keep showing the current value while newer
+ * work is loading, refreshing, retrying, or recovering. This module includes
+ * constructors, checks, accessors, mapping and matching helpers, ways to combine
+ * several results, and schemas for encoding or decoding results.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/Atom.ts

@@ -1,40 +1,12 @@
 /**
- * Reactive state primitives for values evaluated by an {@link AtomRegistry}.
- *
- * An {@link Atom} describes how to read a value. The registry is the runtime
- * owner: it evaluates reads, caches results, records dependency edges, runs
- * effects and streams with the configured runtime services, and disposes nodes
- * when they are no longer observed.
- *
- * **Mental model**
- *
- * Regular `get(atom)` calls inside a read function create dependencies. When a
- * dependency changes or refreshes, dependent atoms are invalidated and re-read
- * on demand. One-shot reads such as `get.once(atom)` read the current value
- * without creating an edge. The same atom can hold different cached values in
- * different registries, so stable atom identity matters; use {@link family} for
- * atoms parameterized by input values.
- *
- * **Common tasks**
- *
- * Use {@link readable} or {@link writable} for synchronous state, {@link make}
- * for effects and streams exposed as `AsyncResult`, {@link fn} for
- * command-style effects, {@link pull} for pull-based streams, and
- * {@link subscriptionRef} to expose a `SubscriptionRef`. Use {@link kvs},
- * {@link searchParam}, and {@link serializable} when atom values need
- * persistence, URL state, or server-to-client hydration. Read and mutate atoms
- * from Effect code with {@link get}, {@link set}, {@link update},
- * {@link refresh}, and {@link mount}; convert observed values to streams with
- * {@link toStream} or {@link toStreamResult}.
- *
- * **Gotchas**
- *
- * Cache lifetime belongs to the registry, not the atom object. Unobserved
- * non-`keepAlive` atoms can be disposed immediately or after their idle TTL,
- * which also releases finalizers and may rebuild effects, streams, and derived
- * state on the next read. Runtime-backed atoms refresh only through their
- * registered refresh hooks or explicit `Reactivity` invalidations; reading an
- * `Effect` by itself does not keep external data subscribed.
+ * Reactive state primitives for values managed by an `AtomRegistry`.
+ *
+ * An `Atom` describes how to produce or update one piece of reactive state. The
+ * registry runs atom reads, remembers current values, tracks dependencies
+ * between atoms, starts effects and streams, and cleans up atoms that are no
+ * longer used. This module includes the atom constructors and update helpers
+ * used for cached values, effect-backed values, streams, browser state, stored
+ * values, and server-rendered values.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AtomHttpApi.ts

@@ -1,30 +1,11 @@
 /**
- * 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.
+ * Connects typed `HttpApi` clients to atoms.
  *
- * 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.
+ * The service created here exposes the generated HTTP API client plus
+ * atom-based query and mutation helpers. Query atoms call endpoints and track
+ * their asynchronous result, while mutations run endpoint calls that can
+ * invalidate reactivity keys after a successful request. Query atoms can also be
+ * cached, serialized for hydration, and kept alive with a time-to-live.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AtomRef.ts

@@ -2,35 +2,10 @@
  * Mutable reactive references for local, in-memory state.
  *
  * `AtomRef` provides small observable state cells that can be read, updated,
- * focused, and subscribed to without going through an `AtomRegistry`. It is
- * suited to form state, local view models, and collections of item references
- * where callers need direct mutation methods together with change notifications.
- *
- * **Mental model**
- *
- * An `AtomRef` is a value cell with a stable key and a subscriber list.
- * {@link make} creates a mutable cell, `map` derives read-only views, and `prop`
- * focuses on nested object or array properties while preserving mutation
- * helpers. {@link collection} stores ordered item refs and emits collection
- * updates when items are inserted, removed, or changed through their refs.
- *
- * **Common tasks**
- *
- * - Use {@link make} for standalone local state.
- * - Use `ref.set` or `ref.update` to replace the current value.
- * - Use `ref.map` for derived read-only values.
- * - Use `ref.prop` to update nested object fields or array entries.
- * - Use {@link collection} for ordered lists whose items should remain
- *   individually mutable.
- *
- * **Gotchas**
- *
- * Notifications are equality-aware: values that are `Equal.equals` to the
- * current value do not notify subscribers, and mapped or property subscriptions
- * only emit when their derived value changes. Directly mutating an object or
- * array stored in a ref does not notify listeners; use `set`, `update`, or a
- * property ref instead. `toArray` returns the current raw item values, not the
- * item refs.
+ * mapped, and subscribed to without going through an `AtomRegistry`. Mutable
+ * refs can also create refs for nested properties. The module also provides a
+ * collection helper that stores item refs and notifies subscribers when items are
+ * inserted, removed, or changed.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AtomRegistry.ts

@@ -1,78 +1,11 @@
 /**
- * The `AtomRegistry` module provides the runtime cache for unstable reactivity
- * atoms. A registry owns the node graph for a group of atoms, stores current
- * values, records parent and child dependencies while atoms are read, and
- * coordinates writes, refreshes, subscriptions, stream conversions, and node
- * disposal.
+ * Stores and runs atoms for one reactive runtime.
  *
- * Use a separate registry for each UI root, request, test, route boundary, or
- * other lifetime that needs isolated atom state. The same atom object can have
- * different cached values in different registries, while serializable atoms use
- * their stable serialization key so preloaded values can hydrate a node before
- * the first read.
- *
- * **Mental model**
- *
- * - Reading an atom creates or reuses a registry node, evaluates the atom when
- *   its value is missing or stale, and records any nested atom reads as
- *   dependencies.
- * - Writing a writable atom updates its node through the atom's write function,
- *   invalidates dependent nodes, and notifies listeners after batching settles.
- * - Subscriptions and scoped {@link mount} calls keep nodes alive. When the last
- *   listener and dependent child disappear, non-`keepAlive` atoms can be
- *   removed immediately or after their idle TTL.
- * - Effects and streams started by atoms run with the registry scheduler and
- *   are finalized when the node is rebuilt, removed, reset, or disposed.
- * - Disposing a registry clears its nodes and makes later atom access an error.
- *
- * **Common tasks**
- *
- * - Create a registry directly with {@link make}, or provide one to Effect
- *   programs with {@link layer} or {@link layerOptions}.
- * - Read and write atom state with the registry instance methods `get`, `set`,
- *   `modify`, `update`, and `refresh`.
- * - Keep an atom alive for an Effect scope with {@link mount}; subscribe with
- *   `subscribe` when integrating with callback-based UI code.
- * - Convert observed atom values with {@link toStream} and
- *   {@link toStreamResult}, or wait for an `AsyncResult` atom with
- *   {@link getResult}.
- * - Preload encoded serializable state with `setSerializable` before the
- *   matching atom is read.
- *
- * **Quickstart**
- *
- * **Example** (Isolated atom state)
- *
- * ```ts
- * import { Atom, AtomRegistry } from "effect/unstable/reactivity"
- *
- * const count = Atom.make(0)
- * const doubled = Atom.make((get) => get(count) * 2)
- *
- * const registry = AtomRegistry.make()
- *
- * registry.set(count, 21)
- * registry.get(doubled)
- * // 42
- * ```
- *
- * **Gotchas**
- *
- * - Atom identity matters. Creating a new atom object creates a different node
- *   unless the atom is serializable and uses the same serialization key.
- * - Unobserved atoms without `keepAlive` can be removed, so later reads may
- *   rebuild derived values, restart effects or streams, and rerun finalizers.
- * - `subscribe` and the instance `mount` method return release callbacks; call
- *   them when the external consumer is done. The exported {@link mount} helper
- *   ties that release to an Effect scope.
- * - `reset` and `dispose` remove every node in the registry. Use a new registry
- *   when a whole lifetime should start from empty state.
- *
- * **See also**
- *
- * - {@link Atom.Atom} for defining reactive values read by a registry.
- * - {@link Result.AsyncResult} for asynchronous atom results.
- * - {@link Stream.Stream} for streams produced from observed atom values.
+ * An `AtomRegistry` evaluates atoms, caches their current values, tracks
+ * dependencies, applies writes and refreshes, manages subscriptions, and
+ * disposes unused nodes. Each registry is independent, so the same atom can hold
+ * different values in different registries. Serializable atom values can also be
+ * preloaded before the first read.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AtomRpc.ts

@@ -1,25 +1,11 @@
 /**
- * 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`.
+ * Connects typed RPC clients to atoms.
  *
- * 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.
+ * The service created here exposes a flattened RPC client plus atom-based query
+ * and mutation helpers. Query atoms call RPCs and track asynchronous or
+ * streaming results, while mutations run RPC calls that can invalidate
+ * reactivity keys after success. Query atoms can also use request headers,
+ * time-to-live settings, and serialization keys for hydration.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/Hydration.ts

@@ -1,35 +1,12 @@
 /**
- * Moves serializable reactivity state between `AtomRegistry` instances.
- *
- * The `Hydration` module snapshots atoms marked with `Atom.serializable` and
- * loads those encoded values into another registry before the atoms are read. It
- * is useful for server rendering, browser bootstrapping, route transitions, and
- * other handoffs where a new registry should start from values computed by a
- * previous one.
- *
- * **Mental model**
- *
- * `dehydrate` walks the source registry and produces `DehydratedAtomValue`
- * records keyed by each atom's serialization key. `hydrate` stores those encoded
- * values in the target registry so the matching atom can decode them with its own
- * serializable codec. Atom identity is not transferred; only the stable key,
- * encoded value, dehydration timestamp, and optional async handoff are.
- *
- * **Common tasks**
- *
- * Use `dehydrate` before rendering or crossing a route boundary, then call
- * `hydrate` on the registry that will serve the next read. Use `toValues` when
- * code accepts generic `DehydratedAtom` entries but needs the concrete record
- * shape, and use `encodeInitialAs` to choose how `AsyncResult.Initial` values
- * should appear in the snapshot.
- *
- * **Gotchas**
- *
- * Only serializable atoms are included, and the target registry must contain
- * atoms with matching stable keys and compatible codecs. The optional
- * `resultPromise` used for `AsyncResult.Initial` is a live JavaScript promise; it
- * can be handed to another registry in the same runtime, but it cannot be sent
- * through JSON or across process boundaries.
+ * Saves and restores serializable atom state.
+ *
+ * `dehydrate` reads atoms marked with `Atom.serializable` from an
+ * `AtomRegistry` and returns encoded entries keyed by their serialization keys.
+ * `hydrate` preloads those entries into another registry before the atoms are
+ * read. Initial `AsyncResult` values can be ignored, encoded as values, or
+ * represented by promises that update the target registry once the result is no
+ * longer initial.
  *
  * @since 4.0.0
  */