effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/unstable/persistence/index.ts

@@ -5,183 +5,36 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * Effectful key/value storage for persistence backends.
- *
- * This module defines the `KeyValueStore` service used by the persistence
- * package when a simple string or binary store is enough. It is useful for
- * lightweight durable state, browser storage, local file-backed data, SQL
- * tables, test stores, and as the storage primitive underneath higher-level
- * persistence APIs.
- *
- * Values are stored as strings or `Uint8Array`s, and `toSchemaStore` adds a
- * schema-aware JSON layer for typed values. Schema changes can make existing
- * JSON fail to decode, and `prefix` should be used to separate namespaces when
- * several logical stores share the same backend. This service does not provide
- * native TTL support; higher-level persistence layers encode expiration
- * metadata in stored values when they need TTLs.
- *
- * Backend behavior is intentionally small but not identical: Web Storage is
- * string-only, `makeStringOnly` stores binary values as base64, filesystem
- * keys become encoded file names, SQL stores value type metadata in a table,
- * and the memory layer is process-local. Choose keys, prefixes, table names,
- * and value formats with those backend constraints in mind.
- *
  * @since 4.0.0
  */
 export * as KeyValueStore from "./KeyValueStore.ts"
 
 /**
- * Defines the request-side contract used by the persistence layer.
- *
- * A `Persistable` request is a `PrimaryKey` value that carries the success and
- * error schemas needed to encode and decode the stored `Exit` for that request.
- * Persisted request resolvers and `PersistedCache` use this metadata to restore
- * previous lookup results from a backing store before running the lookup again.
- *
- * Use `Class` for cacheable or durable requests whose results can safely be
- * reused across fibers, processes, or restarts. The request primary key is the
- * entry id inside a persistence store, so it should be stable, collision-free,
- * and usually include a request-specific prefix. The `storeId` is configured on
- * `Persistence` or `PersistedCache`; it selects the backing store namespace and
- * is separate from the request primary key.
- *
- * Success and error schemas are encoded with the JSON codec, so persisted
- * values must be representable by those schemas and any required schema services
- * must be available where the store reads or writes entries. Changing a schema,
- * primary-key format, or store id can make existing persisted values fail to
- * decode or stop being found, so treat those changes as persistence migrations.
- *
  * @since 4.0.0
  */
 export * as Persistable from "./Persistable.ts"
 
 /**
- * Persistent caching for `Persistable` request keys.
- *
- * A `PersistedCache` combines a scoped in-memory `Cache` with a named
- * `Persistence` store. It is useful for expensive or idempotent lookups such as
- * remote API calls, database reads, and request results that should be reused
- * across fibers, process restarts, or multiple workers sharing the same backing
- * store.
- *
- * The persistent `timeToLive` is evaluated for the stored `Exit`, so successes
- * and failures can be cached with different lifetimes. The in-memory cache has
- * its own `inMemoryTTL` and capacity, and `invalidate` removes both the
- * persisted value and the in-memory entry. Persisted values are encoded with
- * the key's success and error schemas and stored under the key's primary key, so
- * schema changes, primary-key changes, or store-id collisions can make old
- * entries fail to decode until they are invalidated or written under a new
- * `storeId`.
- *
  * @since 4.0.0
  */
 export * as PersistedCache from "./PersistedCache.ts"
 
 /**
- * Schema-aware persisted queues for background work.
- *
- * A `PersistedQueue` stores JSON-encoded values in a named queue and lets
- * workers `take` one value at a time inside a scoped processing window. It is
- * useful for durable handoffs, background jobs, outbox-style integrations, and
- * workloads where failed work should be retried across fibers, process
- * restarts, or multiple workers sharing Redis or SQL.
- *
- * Delivery is at-least-once: a handler that fails, is interrupted, or loses its
- * backing-store lock may see the same element again until `maxAttempts` is
- * reached. Use stable custom ids when offering idempotent work, and choose ids
- * that are collision-free for the backing store because stores can enforce
- * uniqueness at the queue, prefix, or table level. Ordering is intentionally a
- * store-level concern; retries, lock expiration, polling, and multiple workers
- * can move entries behind newer work, so handlers should not rely on strict
- * FIFO processing.
- *
- * Values are encoded and decoded with the supplied schema using the JSON codec,
- * so schema services must be available when offering and taking values. Changing
- * a queue name, schema, Redis prefix, SQL table, or id format is a persistence
- * migration: old entries may decode differently, stop being visible, or collide
- * with new entries. The memory store is process-local and volatile, while Redis
- * and SQL stores use leases that should be tuned for the expected processing
- * time.
- *
  * @since 4.0.0
  */
 export * as PersistedQueue from "./PersistedQueue.ts"
 
 /**
- * Durable storage for encoded `Persistable` request results.
- *
- * The `Persistence` service creates scoped stores that read and write
- * schema-encoded `Exit` values keyed by each request's `PrimaryKey`. It is the
- * lower-level persistence layer used by `PersistedCache` and similar request
- * workflows to reuse expensive or idempotent lookup results across fibers,
- * process restarts, and workers that share a backing store.
- *
- * Each store is selected by a `storeId`, while each entry id comes from the
- * request's primary key. Keep both stable and collision-free: changing the
- * `storeId`, the primary-key format, or the success/error schemas is a
- * persistence migration, because old entries may stop being found or fail to
- * decode. Values are encoded with the request's success and error schemas using
- * the JSON codec, so any required schema services must be available at store
- * read and write time, and the backing value must stay JSON-compatible.
- *
- * TTLs are computed from the stored `Exit` and request key. Infinite TTLs are
- * stored without an expiration, finite TTLs become backing-store expirations,
- * and zero or negative TTLs skip the write entirely. Backing layers provide
- * process-local memory, `KeyValueStore`, Redis, and SQL implementations; store
- * ids are used as prefixes, table names, or SQL partitions and should be
- * chosen with the target backing store in mind.
- *
  * @since 4.0.0
  */
 export * as Persistence from "./Persistence.ts"
 
 /**
- * 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.
- *
  * @since 4.0.0
  */
 export * as RateLimiter from "./RateLimiter.ts"
 
 /**
- * Low-level Redis integration for the persistence modules.
- *
- * This module defines the `Redis` service used by Redis-backed persistence,
- * persisted queues, and rate limiter stores. It adapts an external Redis
- * connection to Effect through `send` for raw commands and `eval` for typed
- * Lua scripts that are loaded with `SCRIPT LOAD` and executed with `EVALSHA`.
- *
- * The service does not create or manage Redis connections; callers provide a
- * command sender from their Redis client or pool. Higher-level stores layer on
- * key prefixes and store ids, so choose stable prefixes to avoid collisions
- * and remember that schema or primary-key changes can make previously persisted
- * JSON values fail to decode. Finite TTLs in the persistence stores are applied
- * with millisecond Redis expirations, while non-finite TTLs are stored without
- * expiration. Script parameters are stringified before execution, and the
- * script descriptor's key count controls how Redis splits `KEYS` from `ARGV`.
- *
  * @since 4.0.0
  */
 export * as Redis from "./Redis.ts"

package/src/unstable/process/ChildProcessSpawner.ts

@@ -1,8 +1,20 @@
 /**
- * A module providing a generic service interface for spawning child processes.
+ * Service contract and helpers for running child processes through Effect.
  *
- * This module provides the `ChildProcessSpawner` service tag which can be
- * implemented by platform-specific packages (e.g., Node.js).
+ * 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.
  *
  * @since 4.0.0
  */

package/src/unstable/process/index.ts

@@ -5,56 +5,11 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * An Effect-native module for working with child processes.
- *
- * 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))
- * ```
- *
  * @since 4.0.0
  */
 export * as ChildProcess from "./ChildProcess.ts"
 
 /**
- * A module providing a generic service interface for spawning child processes.
- *
- * This module provides the `ChildProcessSpawner` service tag which can be
- * implemented by platform-specific packages (e.g., Node.js).
- *
  * @since 4.0.0
  */
 export * as ChildProcessSpawner from "./ChildProcessSpawner.ts"

package/src/unstable/reactivity/AsyncResult.ts

@@ -1,23 +1,44 @@
 /**
- * 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.
+ * State containers for asynchronous values used by the reactivity APIs.
  *
- * 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.
+ * `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.
  *
- * 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.
+ * **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.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/Atom.ts

@@ -1,26 +1,40 @@
 /**
- * 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.
+ * 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.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AtomRef.ts

@@ -1,20 +1,36 @@
 /**
- * Mutable reactive references for local, in-memory state that should be read,
- * updated, and observed without going through an `AtomRegistry`.
+ * Mutable reactive references for local, in-memory state.
  *
- * `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`.
+ * `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.
  *
- * 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.
+ * **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.
  *
  * @since 4.0.0
  */
@@ -137,25 +153,36 @@ class ReadonlyRefImpl<A> implements ReadonlyRef<A> {
     return Hash.hash(this.value)
   }
 
-  listeners: Array<(a: A) => void> = []
-  listenerCount = 0
+  listeners: Listener<A> | null = null
 
   notify(a: A) {
-    for (let i = 0; i < this.listenerCount; i++) {
-      this.listeners[i](a)
+    let listener = this.listeners
+    while (listener !== null) {
+      listener.f(a)
+      listener = listener.next
     }
   }
 
   subscribe(f: (a: A) => void): () => void {
-    this.listeners.push(f)
-    this.listenerCount++
+    const listener: Listener<A> = {
+      f,
+      prev: null,
+      next: this.listeners
+    }
+    if (this.listeners) {
+      this.listeners.prev = listener
+    }
+    this.listeners = listener
 
     return () => {
-      const index = this.listeners.indexOf(f)
-      if (index !== -1) {
-        this.listeners[index] = this.listeners[this.listenerCount - 1]
-        this.listeners.pop()
-        this.listenerCount--
+      if (this.listeners === listener) {
+        this.listeners = listener.next
+      }
+      if (listener.prev) {
+        listener.prev.next = listener.next
+      }
+      if (listener.next) {
+        listener.next.prev = listener.prev
       }
     }
   }
@@ -165,6 +192,12 @@ class ReadonlyRefImpl<A> implements ReadonlyRef<A> {
   }
 }
 
+type Listener<A> = {
+  readonly f: (a: A) => void
+  prev: Listener<A> | null
+  next: Listener<A> | null
+}
+
 class AtomRefImpl<A> extends ReadonlyRefImpl<A> implements AtomRef<A> {
   prop<K extends keyof A>(prop: K): AtomRef<A[K]> {
     return new PropRefImpl(this, prop)

package/src/unstable/reactivity/AtomRegistry.ts

@@ -1,22 +1,78 @@
 /**
- * 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.
+ * 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.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * **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.
  *
  * @since 4.0.0
  */