effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/cluster/Runners.ts

@@ -67,7 +67,7 @@ import * as Snowflake from "./Snowflake.ts"
  */
 export class Runners extends Context.Service<Runners, {
   /**
-   * Checks if a Runner is responsive.
+   * Checks whether a Runner is responsive.
    */
   readonly ping: (address: RunnerAddress) => Effect.Effect<void, RunnerUnavailable>
 
@@ -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

@@ -55,8 +55,8 @@ export interface ShardId extends Equal.Equal, Hash.Hash, PrimaryKey.PrimaryKey {
 export const isShardId = (u: unknown): u is ShardId => hasProperty(u, TypeId)
 
 /**
- * Schema for `ShardId` values encoded as `{ group, id }` objects and decoded via
- * `make`.
+ * Schema for shard identifiers encoded as `{ group, id }` objects and decoded
+ * via `make`.
  *
  * @category schemas
  * @since 4.0.0
@@ -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
  */
@@ -84,11 +103,16 @@ import { SingletonAddress } from "./SingletonAddress.ts"
 import * as Snowflake from "./Snowflake.ts"
 
 /**
- * Cluster sharding service for registering entities and singletons, routing
- * messages to owned shards, generating runner-local snowflake ids, and polling
+ * Service that registers entities and singletons, routes messages to owned
+ * shards, generates runner-local snowflake ids, and polls
  * storage for persisted work.
  *
- * @category models
+ * **When to use**
+ *
+ * Use to access or provide cluster routing, shard ownership, entity
+ * registration, singleton registration, and persisted-work polling.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class Sharding extends Context.Service<Sharding, {
@@ -1461,6 +1485,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
  */
@@ -195,10 +239,10 @@ export const layer = (options?: Partial<ShardingConfig["Service"]>): Layer.Layer
 export const layerDefaults: Layer.Layer<ShardingConfig> = layer()
 
 /**
- * Config descriptor for loading `ShardingConfig` values, applying the same
+ * Describes how to load `ShardingConfig` values, applying the same
  * defaults used by the in-memory `defaults` object.
  *
- * @category Config
+ * @category configuration
  * @since 4.0.0
  */
 export const config: Config.Config<ShardingConfig["Service"]> = Config.all({
@@ -301,7 +345,7 @@ export const config: Config.Config<ShardingConfig["Service"]> = Config.all({
  * Effect that loads `ShardingConfig` from environment variables using the
  * constant-case config provider.
  *
- * @category Config
+ * @category configuration
  * @since 4.0.0
  */
 export const configFromEnv = config.pipe(

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
  */
@@ -53,8 +67,7 @@ export interface SingletonRegistered {
 }
 
 /**
- * Generated helpers for pattern matching and constructing sharding registration
- * events.
+ * Constructors and matchers for sharding registration events.
  *
  * @category pattern matching
  * @since 4.0.0

package/src/unstable/cluster/SingleRunner.ts

@@ -36,9 +36,34 @@ import * as SqlMessageStorage from "./SqlMessageStorage.ts"
 import * as SqlRunnerStorage from "./SqlRunnerStorage.ts"
 
 /**
- * A sql backed single-node cluster, that can be used for running durable
+ * Provides a SQL-backed single-node cluster 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

@@ -56,9 +56,10 @@ export type TypeId = typeof TypeId
 export type Snowflake = Brand.Branded<bigint, TypeId>
 
 /**
- * Constructs a branded `Snowflake` from a bigint or bigint-compatible string.
+ * Constructs a branded cluster snowflake id from a bigint or bigint-compatible
+ * string.
  *
- * @category models
+ * @category constructors
  * @since 4.0.0
  */
 export const Snowflake = (input: string | bigint): Snowflake =>
@@ -132,9 +133,9 @@ export const SnowflakeFromString: SnowflakeFromString = Schema.String.pipe(
 )
 
 /**
- * Custom snowflake epoch in Unix milliseconds, set to January 1, 2025 UTC.
+ * Defines the custom snowflake epoch in Unix milliseconds.
  *
- * @category Epoch
+ * @category constants
  * @since 4.0.0
  */
 export const constEpochMillis: number = Date.UTC(2025, 0, 1)
@@ -146,10 +147,23 @@ const constBigInt1024 = BigInt(1024)
 const constBigInt4096 = BigInt(4096)
 
 /**
- * Packs a timestamp, machine id, and sequence number into a branded snowflake id,
+ * Creates a branded snowflake id from a timestamp, machine id, and sequence number,
  * 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
  */
@@ -70,9 +91,14 @@ export const layer: Layer.Layer<
 )
 
 /**
- * Client-only socket runner layer that provides `Sharding` and `Runners` clients
+ * Provides a client-only socket runner layer that provides `Sharding` and `Runners` clients
  * without starting a runner server or receiving shard assignments.
  *
+ * **When to use**
+ *
+ * Use to join a socket-based cluster as a client-only participant that can send
+ * messages without hosting shards.
+ *
  * @category layers
  * @since 4.0.0
  */