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

package/src/unstable/cluster/RunnerAddress.ts

@@ -1,19 +1,36 @@
 /**
- * The `RunnerAddress` module defines the network identity used to locate a
- * cluster runner. A runner address is a host and port pair that can be encoded,
- * compared, hashed, inspected, and used as a stable primary key.
+ * The `RunnerAddress` module defines the stable network identity used to locate
+ * a cluster runner. A runner address is a host and port pair that can be
+ * encoded with its schema, compared structurally, hashed, inspected, and used as
+ * a primary key in runner registries and shard ownership data.
  *
- * **Common use cases**
+ * **Mental model**
  *
- * - Representing the target runner for cluster routing and placement decisions
- * - Persisting or exchanging runner endpoints through schemas
- * - Using runner endpoints as keys in maps, registries, or shard ownership data
+ * `RunnerAddress` is identity data, not connection configuration. Equality,
+ * hashing, and the primary key all use the host and port exactly as supplied,
+ * so callers should normalize host names before constructing the value when the
+ * surrounding routing layer requires a canonical form.
+ *
+ * **Common tasks**
+ *
+ * - Build runner endpoints with {@link make}.
+ * - Persist or exchange runner endpoints through the {@link RunnerAddress}
+ *   schema.
+ * - Use addresses as stable keys in runner maps, registries, and shard ownership
+ *   records.
  *
  * **Gotchas**
  *
- * - Identity is structural: two addresses are equal when both host and port match
+ * - Identity is structural: two addresses are equal only when both host and port
+ *   match.
  * - The primary key is formatted as `host:port`, so host strings should already
- *   be normalized for the routing layer using them
+ *   be normalized for the routing layer using them.
+ * - The constructor does not check whether the endpoint is reachable.
+ *
+ * **See also**
+ *
+ * - {@link RunnerAddress}
+ * - {@link make}
  *
  * @since 4.0.0
  */
@@ -91,6 +108,25 @@ export class RunnerAddress extends Schema.Class<RunnerAddress>(TypeId)({
 /**
  * Constructs a `RunnerAddress` from a host and port.
  *
+ * **When to use**
+ *
+ * Use to create the stable network identity for a cluster runner when
+ * configuring sharding, registering runner metadata, or targeting a runner by
+ * host and port.
+ *
+ * **Details**
+ *
+ * The returned `RunnerAddress` stores the supplied `host` and `port`. Equality,
+ * hashing, and the primary key use both fields, with the primary key formatted
+ * as `host:port`.
+ *
+ * **Gotchas**
+ *
+ * `make` does not normalize the host. Pass the host string exactly as the
+ * cluster routing and storage layers should identify it.
+ *
+ * @see {@link RunnerAddress} for the constructed address type and its equality, hashing, primary-key, and formatting behavior
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/RunnerHealth.ts

@@ -1,23 +1,40 @@
 /**
- * The `RunnerHealth` module defines the health-check service used by cluster
- * sharding to decide whether a runner may still own its assigned shards. A
- * runner that is reported as alive is allowed to keep processing messages,
- * while a runner that is reported as unavailable can have its shards moved to
- * another runner.
+ * The `RunnerHealth` module defines the health-check service used by the
+ * unstable cluster runtime when deciding whether a runner can keep ownership of
+ * its assigned shards. The service answers whether a runner address is alive
+ * enough for sharding to keep routing work to it.
+ *
+ * **Mental model**
+ *
+ * Runner health feeds placement decisions, not process supervision. A healthy
+ * result lets the current runner continue serving its entities, while an
+ * unhealthy result allows sharding to move those shards to another runner. Keep
+ * checks conservative: a runner reported as unavailable may still be finishing
+ * in-flight messages.
  *
  * **Common tasks**
  *
- * - Provide a custom {@link RunnerHealth} service for a cluster deployment
- * - Use {@link layerPing} to check runners through the cluster runner protocol
- * - Use {@link layerK8s} when Kubernetes pod readiness should drive health
- * - Use {@link layerNoop} in tests or environments where runners are always considered healthy
+ * - Provide a custom {@link RunnerHealth} service for deployment-specific
+ *   failure detection.
+ * - Use {@link layerPing} to check runners through the cluster runner protocol.
+ * - Use {@link layerK8s} when Kubernetes pod readiness should drive runner
+ *   health.
+ * - Use {@link layerNoop} in tests or single-runner environments where every
+ *   runner should be treated as healthy.
  *
  * **Gotchas**
  *
- * - Health checks affect shard reassignment, so false negatives can move shards
- *   away from runners that may still be processing messages
+ * - False negatives can trigger shard reassignment away from runners that are
+ *   still processing messages.
  * - The Kubernetes implementation treats API failures as healthy to avoid
- *   reassignment caused by a temporary control-plane outage
+ *   reassignment caused by a temporary control-plane outage.
+ * - {@link layerNoop} disables failure detection for this decision point, so it
+ *   should only be used when that tradeoff is intentional.
+ *
+ * **See also**
+ *
+ * - {@link RunnerHealth}
+ * - {@link layerPing}, {@link layerK8s}, and {@link layerNoop}
  *
  * @since 4.0.0
  */
@@ -54,7 +71,7 @@ export class RunnerHealth extends Context.Service<
  *
  * **When to use**
  *
- * This is useful for testing.
+ * Use when this is useful for testing.
  *
  * @category layers
  * @since 4.0.0

package/src/unstable/cluster/RunnerServer.ts

@@ -160,6 +160,20 @@ const constWaitUntilRead = { waitUntilRead: true } as const
  * runners, forwards them to the `Sharding` layer, and responds to `Ping`
  * requests.
  *
+ * **When to use**
+ *
+ * Use when a runner process should accept runner-to-runner protocol messages
+ * over a provided server `RpcServer.Protocol`.
+ *
+ * **Gotchas**
+ *
+ * This layer does not choose or provide the wire transport; provide a
+ * transport-specific `RpcServer.Protocol` separately.
+ *
+ * @see {@link layerHandlers} for the lower-level handler layer used when the RPC server is supplied elsewhere
+ * @see {@link layerWithClients} for a runner server layer that also provides the `Sharding` and `Runners` clients
+ * @see {@link layerClientOnly} for embedding a cluster client without serving runner RPCs
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -197,7 +211,7 @@ export const layerWithClients: Layer.Layer<
  *
  * **When to use**
  *
- * Use this layer to embed a cluster client inside another Effect application
+ * Use when you use this layer to embed a cluster client inside another Effect application
  * without registering with the ShardManager or receiving shard assignments.
  *
  * @category layers

package/src/unstable/cluster/Runners.ts

@@ -150,6 +150,30 @@ export class Runners extends Context.Service<Runners, {
  * message persistence, duplicate request handling, optional local serialization
  * simulation, and polling for persisted replies.
  *
+ * **When to use**
+ *
+ * Use to build a custom `Runners` service when you already have remote `ping`,
+ * `send`, `notify`, and `onRunnerUnavailable` callbacks and want the standard
+ * local persistence and reply recovery behavior added around them.
+ *
+ * **Details**
+ *
+ * `make` uses the supplied remote callbacks for runner communication and
+ * derives `sendLocal` and `notifyLocal`. Local sends can optionally simulate
+ * remote serialization, persisted notifications are saved through
+ * `MessageStorage`, duplicate requests are resumed from stored replies when
+ * possible, and pending replies are polled according to
+ * `ShardingConfig.entityReplyPollInterval`.
+ *
+ * **Gotchas**
+ *
+ * `notify` and `notifyLocal` only support RPCs annotated as persisted; calling
+ * either path with a non-persisted message dies instead of returning a typed
+ * error.
+ *
+ * @see {@link makeRpc} for the RPC-backed implementation built on top of this constructor
+ * @see {@link makeNoop} for a no-op implementation when remote runner communication is not needed
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/ShardId.ts

@@ -79,6 +79,28 @@ export const ShardId = S.declare(isShardId, {
  * Creates or reuses the cached `ShardId` for the specified shard group and numeric
  * id.
  *
+ * **When to use**
+ *
+ * Use to create a `ShardId` when the shard group and numeric id are already
+ * known, such as after a routing decision or after decoding stored shard-id
+ * parts.
+ *
+ * **Details**
+ *
+ * Repeated calls with the same `group` and `id` return the same cached
+ * `ShardId` instance. The returned value stores those fields, compares by
+ * `group` and `id`, formats as `group:id`, and uses that string form for
+ * hashing and primary keys.
+ *
+ * **Gotchas**
+ *
+ * `make` does not compute a shard from an entity id or check whether the shard
+ * belongs to the current sharding configuration. Pass the shard group and
+ * numeric id produced by the routing or storage layer.
+ *
+ * @see {@link toString} for formatting an existing shard id as `group:id`
+ * @see {@link fromString} for constructing a cached shard id from the `group:id` string form
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/Sharding.ts

@@ -1,25 +1,44 @@
 /**
- * The `Sharding` module coordinates cluster-wide placement and delivery for
- * entities and singletons. It hashes entity ids into shard ids, tracks which
- * runner owns each shard, acquires local shard locks, and routes RPC messages
- * to the runner that is responsible for the addressed entity.
+ * The `Sharding` module provides the runtime service that maps entity ids to
+ * shard ids, decides which runner owns each shard, and delivers cluster
+ * messages to the owning runner. It connects typed entity protocols with runner
+ * membership, shard locks, mailbox storage, and the transport used between
+ * runners.
  *
- * Use this module when building clustered services that need location
- * transparency for stateful entities, singleton workloads that should run once
- * per shard group, or durable message processing backed by cluster storage.
- * Registered entity handlers are started on demand for shards owned by the
- * current runner, while clients produced by the {@link Sharding} service route
- * requests through the sharding service instead of calling handlers directly.
+ * **Mental model**
+ *
+ * - Entity ids are hashed into shard ids inside a shard group.
+ * - Healthy runners are placed on a hash ring for each shard group.
+ * - The local runner starts handlers only for shards it currently owns.
+ * - Clients created by {@link Sharding.Service.makeClient} route encoded RPC requests
+ *   to the current owner instead of calling handlers directly.
+ * - Persisted messages are polled from storage and replayed only for shards the
+ *   local runner owns.
+ *
+ * **Common tasks**
+ *
+ * - Register entity handlers with {@link Sharding.Service.registerEntity}.
+ * - Register singleton effects that run once per shard group with
+ *   {@link Sharding.Service.registerSingleton}.
+ * - Build typed entity clients with {@link Sharding.Service.makeClient}.
+ * - Send an already encoded incoming message with {@link Sharding.Service.send}.
+ * - Generate runner-local snowflake ids with {@link Sharding.Service.getSnowflake}.
  *
  * **Gotchas**
  *
- * - Shard assignment and shard acquisition are distinct: a runner may be
- *   assigned a shard before it has acquired the storage lock for that shard.
- * - Routing depends on the entity shard group and the configured shard count,
- *   so changing either value affects where entity ids are placed.
- * - Persisted messages are only read and dispatched for shards currently owned
- *   by the local runner; shutdown and runner health changes can temporarily
- *   move work between runners.
+ * - Assignment and acquisition are separate: a runner may be assigned a shard
+ *   before it has acquired the storage lock.
+ * - Changing shard group names, shard counts, or runner weights changes
+ *   placement for entity ids.
+ * - Ownership can move during shutdown, runner failure, or health refreshes, so
+ *   callers must handle routing and mailbox errors.
+ * - Durable replay depends on the configured message storage; in-memory storage
+ *   does not provide process restart recovery.
+ *
+ * **See also**
+ *
+ * - {@link ShardingConfig} for runner identity, shard counts, and timing.
+ * - {@link Runner} for the membership record used during shard assignment.
  *
  * @since 4.0.0
  */
@@ -1461,6 +1480,25 @@ const make = Effect.gen(function*() {
  * runner communication, message storage, runner storage, runner health, the
  * snowflake generator, and the entity reaper.
  *
+ * **When to use**
+ *
+ * Use when assembling a cluster sharding runtime from explicit sharding
+ * configuration, runner communication, message storage, runner storage, and
+ * runner health layers.
+ *
+ * **Details**
+ *
+ * The layer provides the `Sharding` service and installs its own snowflake
+ * generator and entity reaper. Callers still provide `ShardingConfig`,
+ * `Runners`, `MessageStorage`, `RunnerStorage`, and `RunnerHealth`.
+ *
+ * **Gotchas**
+ *
+ * Persisted messages require a non-no-op `MessageStorage`; if this layer is
+ * provided with `MessageStorage.layerNoop`, persisted sends defect.
+ *
+ * @see {@link Sharding} for the service provided by this layer
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/cluster/ShardingConfig.ts

@@ -1,18 +1,39 @@
 /**
- * The `ShardingConfig` module defines the configuration used by a cluster
- * runner to participate in Effect Cluster sharding. It describes how a runner is
- * addressed by other runners, which shard groups it can host, how many shards
- * are assigned per group, and the timing settings used for locks, assignment
- * refreshes, health checks, entity lifecycle, and message polling.
+ * The `ShardingConfig` module describes how an Effect Cluster runner joins and
+ * participates in sharding. It combines the runner network identity, shard group
+ * membership, shard-count and weight settings, storage-lock timing, entity
+ * mailbox and lifecycle limits, and polling intervals used by the local runner.
  *
- * Use this module when wiring a sharded application locally with
- * {@link layer}, loading deployment settings from environment variables with
- * {@link layerFromEnv}, or overriding selected defaults for tests and
- * single-node development. In production, keep cluster-wide values such as
- * `shardsPerGroup` and shard groups consistent across runners, choose stable
- * externally reachable runner addresses, and tune lock expiration and refresh
- * intervals to match the storage backend and shutdown behavior of the
- * deployment platform.
+ * **Mental model**
+ *
+ * - {@link ShardingConfig} is provided as a service so cluster components read
+ *   one consistent set of sharding settings.
+ * - {@link defaults} is the local-development baseline; {@link layer} overlays
+ *   explicit values, and {@link layerFromEnv} loads constant-case environment
+ *   variables before applying optional overrides.
+ * - `runnerAddress` is the externally reachable address advertised to other
+ *   runners; `runnerListenAddress` can differ when the process binds a
+ *   different interface.
+ * - `availableShardGroups`, `assignedShardGroups`, `shardsPerGroup`, and
+ *   `runnerShardWeight` decide which shards a runner may own and how assignment
+ *   is balanced.
+ *
+ * **Common tasks**
+ *
+ * - Provide default local configuration with {@link layerDefaults}.
+ * - Override selected fields in code with {@link layer}.
+ * - Load deployment configuration from the environment with
+ *   {@link configFromEnv} or {@link layerFromEnv}.
+ * - Normalize configured shard groups with {@link shardGroupConfig}.
+ *
+ * **Gotchas**
+ *
+ * - Keep cluster-wide values such as `availableShardGroups` and
+ *   `shardsPerGroup` consistent for runners sharing the same storage backend.
+ * - Use stable, reachable `runnerAddress` values; client-only nodes should use
+ *   `Option.none()` for `runnerAddress`.
+ * - Tune lock expiration, refresh intervals, and termination timeouts together
+ *   so normal shutdown does not look like runner failure.
  *
  * @since 4.0.0
  */
@@ -180,6 +201,29 @@ export const defaults: ShardingConfig["Service"] = {
  * Creates a `ShardingConfig` layer by merging the provided partial options over
  * `defaults`.
  *
+ * **When to use**
+ *
+ * Use when wiring a cluster runner with explicit `ShardingConfig` values,
+ * especially in tests, local development, or code paths where configuration
+ * should be provided programmatically instead of loaded from environment
+ * variables.
+ *
+ * **Details**
+ *
+ * The merge is shallow: omitted fields use `defaults`, and provided fields
+ * replace the corresponding default value.
+ *
+ * **Gotchas**
+ *
+ * This layer only merges and provides configuration; it does not check that
+ * cluster-wide settings are consistent across runners. Keep values such as
+ * `shardsPerGroup` and `availableShardGroups` aligned for runners that should
+ * share shard assignments.
+ *
+ * @see {@link defaults} for the values used when an option is omitted
+ * @see {@link layerDefaults} for a layer with no overrides
+ * @see {@link layerFromEnv} for loading configuration from environment variables before applying explicit overrides
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/cluster/ShardingRegistrationEvent.ts

@@ -1,17 +1,31 @@
 /**
- * The `ShardingRegistrationEvent` module defines the events emitted by
- * `Sharding` when the local runner registers entity handlers or singleton
- * workloads. These events are useful for observing the set of capabilities a
- * runner has made available, coordinating startup hooks, and writing tests or
- * integrations that need to react when registrations are complete.
+ * The `ShardingRegistrationEvent` module models the live notifications emitted
+ * by `Sharding` when the local runner registers an entity handler or singleton.
+ * Consumers can use these events to wait for registrations during startup,
+ * inspect which capabilities a runner made available, or assert registration
+ * behavior in tests.
  *
- * Registration events describe local registration, not shard ownership or
- * execution. A runner may register an entity or singleton before it owns the
- * shard that will run it, and the events are in-memory notifications from the
- * `Sharding` service rather than persisted cluster state. For persisted
- * messages, treat registration as the point where the handler is available to
- * the runner; it does not imply that existing storage work has already been
- * read or processed.
+ * **Mental model**
+ *
+ * Registration is local capability discovery. An `EntityRegistered` event means
+ * this runner has installed handlers for an entity type; a `SingletonRegistered`
+ * event carries the `SingletonAddress` computed for the singleton name and shard
+ * group. Neither event means the runner currently owns the relevant shard or has
+ * started processing stored messages.
+ *
+ * **Common tasks**
+ *
+ * - Consume `Sharding.getRegistrationEvents` in tests or startup coordination
+ * - Match on entity and singleton registrations with the generated `match`
+ *   helper
+ * - Record registered entity types and singleton addresses for diagnostics
+ *
+ * **Gotchas**
+ *
+ * - Events are live in-memory notifications; they are not stored or replayed for
+ *   later subscribers
+ * - Shard acquisition, singleton execution, and persisted mailbox polling happen
+ *   after registration and may move as runner membership changes
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/SingleRunner.ts

@@ -39,6 +39,31 @@ import * as SqlRunnerStorage from "./SqlRunnerStorage.ts"
  * A sql backed single-node cluster, that can be used for running durable
  * entities and workflows.
  *
+ * **When to use**
+ *
+ * Use to run durable cluster entities and workflows in a local, embedded, or
+ * small single-node process while keeping mailbox and reply state in SQL.
+ *
+ * **Details**
+ *
+ * The layer provides `Sharding`, `Runners`, and `MessageStorage`. It loads
+ * `ShardingConfig` from environment variables and overlays
+ * `options.shardingConfig` when provided. Message storage is always SQL-backed;
+ * runner storage is SQL-backed by default and switches to in-memory storage
+ * when `runnerStorage` is set to `"memory"`.
+ *
+ * **Gotchas**
+ *
+ * - Even when `runnerStorage` is `"memory"`, message storage remains
+ *   SQL-backed, so callers must still provide `SqlClient`.
+ * - Runner communication and runner health are no-op services, so this layer is
+ *   for single-process use rather than multi-runner coordination.
+ *
+ * @see {@link ShardingConfig.layerFromEnv} for loading environment configuration before applying `shardingConfig` overrides
+ * @see {@link SqlMessageStorage.layer} for the SQL-backed message storage that this layer provides
+ * @see {@link SqlRunnerStorage.layer} for the default SQL-backed runner storage selected when `runnerStorage` is omitted or `"sql"`
+ * @see {@link RunnerStorage.layerMemory} for the in-memory runner storage selected by `runnerStorage: "memory"`
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/cluster/Singleton.ts

@@ -1,14 +1,33 @@
 /**
- * The `Singleton` module provides a small helper for registering effects that
- * should run once across an Effect cluster. A singleton is coordinated through
- * `Sharding`, which assigns ownership to one node at a time and can move that
- * ownership when nodes leave or fail.
+ * Register effects that should have one active owner in an Effect cluster.
  *
- * Use singletons for cluster-wide background work such as schedulers, polling
- * loops, maintenance jobs, or consumers that must not have one instance per
- * process. Because ownership can change during failover, the registered effect
- * should be interruptible, scoped, and able to resume work without assuming that
- * the previous owner completed every in-flight action exactly once.
+ * `Singleton.make` wraps `Sharding.registerSingleton` in a `Layer`. When the
+ * local runner owns the shard for the singleton's name and shard group,
+ * sharding starts the effect; when ownership moves or the layer scope closes,
+ * the running fiber is interrupted and the registration is removed.
+ *
+ * **Mental model**
+ *
+ * A singleton is still placed on a shard. Its name and optional shard group
+ * determine the shard id, and the runner that acquires that shard lock is the
+ * only runner allowed to execute it. Failover is handled by shard ownership, so
+ * another runner can resume the singleton after the previous owner leaves.
+ *
+ * **Common tasks**
+ *
+ * - Start one scheduler, consumer, polling loop, or maintenance process for a
+ *   whole cluster
+ * - Register that process as part of application wiring with `Layer`
+ * - Choose a `shardGroup` when singleton ownership should be coordinated with a
+ *   specific group of clustered work
+ *
+ * **Gotchas**
+ *
+ * - Design the effect to be interruptible and idempotent; ownership can move
+ *   while work is in flight.
+ * - Duplicate singleton names in the same shard group fail during registration.
+ * - Handle expected failures inside the effect when it should keep running,
+ *   because unhandled failures are surfaced as defects by sharding.
  *
  * @since 4.0.0
  */
@@ -21,6 +40,29 @@ import { Sharding } from "./Sharding.ts"
  * Creates a layer that registers a singleton effect with `Sharding` under the
  * specified name and optional shard group.
  *
+ * **When to use**
+ *
+ * Use to register a cluster-wide background effect as a `Layer`, so the effect
+ * is started only by the runner that currently owns the singleton's shard.
+ *
+ * **Details**
+ *
+ * The returned layer requires `Sharding` and the services needed by `run`,
+ * except for `Scope`. The registration is scoped to the layer; closing the
+ * layer removes the singleton registration and stops the singleton fiber if it
+ * is running.
+ *
+ * **Gotchas**
+ *
+ * - Registering the same singleton name in the same shard group more than once
+ *   dies during registration.
+ * - A `run` effect that completes normally is kept alive until the registration
+ *   scope closes or shard ownership moves.
+ * - Failures from `run` are converted to defects, so handle expected failures
+ *   inside `run` when the singleton should keep running.
+ *
+ * @see {@link Sharding} for the lower-level service that registers singletons and manages shard ownership
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/SingletonAddress.ts

@@ -1,17 +1,31 @@
 /**
- * The `SingletonAddress` module defines the address used by cluster sharding to
- * identify a registered singleton. A singleton address combines the singleton
- * name with the `ShardId` that owns it, giving the runtime a stable key for
- * registration events, equality checks, hashing, and runner-local fiber
- * tracking.
- *
- * Use this module when observing singleton registrations or working with
- * sharding internals that need to tell which shard currently owns a singleton.
- * The shard id is derived from the singleton name and shard group at
- * registration time, so changing either value changes ownership and routing.
- * Ownership can also move as shard locks are acquired or released, so an address
- * identifies the target shard rather than guaranteeing that a particular runner
- * is currently executing the singleton.
+ * The `SingletonAddress` module models the runtime address assigned to a cluster
+ * singleton registration. The address pairs the singleton `name` with the
+ * `ShardId` selected from that name and its shard group, giving sharding one
+ * stable value for registration events, equality, hashing, and local singleton
+ * fiber tracking.
+ *
+ * **Mental model**
+ *
+ * A singleton does not have an entity id supplied by the caller. During
+ * registration, `Sharding` hashes the singleton name within a shard group and
+ * records the resulting shard id next to the name. When the local runner
+ * acquires that shard, the singleton can run; when ownership moves away, the
+ * address stays the same and the local singleton fiber is stopped.
+ *
+ * **Common tasks**
+ *
+ * - Read the address carried by singleton registration events
+ * - Compare singleton registrations by both name and shard id
+ * - Include the name and shard id in logs or diagnostics about singleton
+ *   ownership changes
+ *
+ * **Gotchas**
+ *
+ * - The same singleton name in different shard groups produces different
+ *   addresses
+ * - An address identifies the shard responsible for a singleton, not the runner
+ *   currently executing it
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/Snowflake.ts

@@ -150,6 +150,19 @@ const constBigInt4096 = BigInt(4096)
  * using the custom snowflake epoch and 10-bit machine id and 12-bit sequence
  * fields.
  *
+ * **When to use**
+ *
+ * Use to pack known timestamp, machine id, and sequence parts into a branded
+ * snowflake id when you already control id allocation.
+ *
+ * **Gotchas**
+ *
+ * Machine id values are encoded modulo 1024, and sequence values modulo 4096;
+ * values outside those ranges wrap instead of being rejected.
+ *
+ * @see {@link toParts} for the inverse operation that decodes a snowflake id into timestamp, machine id, and sequence parts
+ * @see {@link makeGenerator} for generating ids with Clock-backed timestamp and sequence management
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/SocketRunner.ts

@@ -51,6 +51,27 @@ const withLogAddress = <A, E, R>(layer: Layer.Layer<A, E, R>): Layer.Layer<A, E,
  * Layer that runs a cluster runner over the socket RPC protocol, providing
  * `Sharding` and `Runners` clients and logging the socket listen address.
  *
+ * **When to use**
+ *
+ * Use when a cluster runner process should accept runner RPCs through a
+ * provided `SocketServer` and receive shard assignments while exposing
+ * `Sharding` and `Runners` services.
+ *
+ * **Details**
+ *
+ * It logs the bound `SocketServer.address` when the layer starts, formatting TCP
+ * addresses as `hostname:port` and Unix socket addresses as their filesystem
+ * path.
+ *
+ * **Gotchas**
+ *
+ * Although this layer serves runner RPCs with the provided `SocketServer`,
+ * outgoing calls to other runners still require a `Runners.RpcClientProtocol`
+ * service.
+ *
+ * @see {@link layerClientOnly} for the socket runner layer that only provides clients and does not receive shard assignments
+ * @see {@link Runners.RpcClientProtocol} for the outgoing runner client protocol required by this layer
+ *
  * @category layers
  * @since 4.0.0
  */