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

package/src/unstable/cluster/MachineId.ts

@@ -1,18 +1,28 @@
 /**
- * The `MachineId` module provides the branded integer identifier used to
- * distinguish cluster runners when generating distributed ids and coordinating
- * runner state.
+ * Branded integer identifiers for cluster runners. A `MachineId` marks the
+ * machine component used by cluster services, especially snowflake id
+ * generation, while keeping the value distinct from an ordinary `number` in
+ * TypeScript APIs.
  *
- * **When to use**
+ * **Mental model**
+ *
+ * The runtime value is still a number. The brand documents that the number was
+ * assigned as a cluster machine id and lets schemas, storage adapters, and
+ * generators agree on the same type.
+ *
+ * **Common tasks**
  *
- * - Persisting or exchanging the machine id assigned to a cluster runner
- * - Passing a runner-specific identity to the cluster snowflake generator
- * - Decoding machine ids from storage while keeping them distinct from plain numbers
+ * - Decode persisted runner identities with the {@link MachineId} schema
+ * - Brand a trusted numeric id with {@link make}
+ * - Pass a runner-specific id to snowflake generation
  *
  * **Gotchas**
  *
- * - Machine ids must be unique for concurrently active runners that generate snowflakes
- * - Snowflake ids store the machine component in 10 bits, so only the value modulo 1024 is encoded
+ * - Concurrent runners that generate snowflakes need distinct machine ids.
+ * - Snowflake ids encode the machine component in 10 bits, so only the value
+ *   modulo 1024 is represented there.
+ * - {@link make} brands a number without validation; use the schema when input
+ *   needs decoding or validation.
  *
  * @since 4.0.0
  */
@@ -42,6 +52,22 @@ export type MachineId = typeof MachineId.Type
 /**
  * Brands a number as a `MachineId`.
  *
+ * **When to use**
+ *
+ * Use to turn a trusted numeric machine id into the branded type when
+ * implementing runner storage adapters or configuring snowflake generation.
+ *
+ * **Details**
+ *
+ * The branded value is the original number at runtime.
+ *
+ * **Gotchas**
+ *
+ * `make` does not validate integer input or enforce the snowflake machine-id
+ * range. Snowflake ids encode the machine component modulo 1024.
+ *
+ * @see {@link MachineId} for the schema that validates branded integer machine identifiers
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/Message.ts

@@ -91,7 +91,7 @@ export const incomingLocalFromOutgoing = <R extends Rpc.Any>(self: Outgoing<R>):
 }
 
 /**
- * Incoming persisted request whose payload has not yet been decoded with the RPC
+ * Represents an incoming persisted request whose payload has not yet been decoded with the RPC
  * schema.
  *
  * **Details**
@@ -109,14 +109,14 @@ export class IncomingRequest<R extends Rpc.Any> extends Data.TaggedClass("Incomi
 }> {}
 
 /**
- * Incoming request for local delivery with a decoded payload.
+ * Represents an incoming request for local delivery with a decoded payload.
  *
  * **Details**
  *
  * It includes dynamic annotations, the last sent reply, and a callback for
  * replying with decoded replies.
  *
- * @category outgoing
+ * @category incoming
  * @since 4.0.0
  */
 export class IncomingRequestLocal<R extends Rpc.Any> extends Data.TaggedClass("IncomingRequestLocal")<{
@@ -127,7 +127,7 @@ export class IncomingRequestLocal<R extends Rpc.Any> extends Data.TaggedClass("I
 }> {}
 
 /**
- * Incoming control envelope carrying an `AckChunk` or `Interrupt`.
+ * Represents an incoming control envelope carrying an `AckChunk` or `Interrupt`.
  *
  * @category incoming
  * @since 4.0.0
@@ -150,7 +150,7 @@ export class IncomingEnvelope extends Data.TaggedClass("IncomingEnvelope")<{
 export type Outgoing<R extends Rpc.Any> = OutgoingRequest<R> | OutgoingEnvelope
 
 /**
- * Outgoing entity request with decoded payload and RPC metadata.
+ * Represents an outgoing entity request with decoded payload and RPC metadata.
  *
  * **Details**
  *
@@ -177,11 +177,11 @@ export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("Outgoi
 }
 
 /**
- * Outgoing control envelope paired with RPC metadata.
+ * Represents an outgoing control envelope paired with RPC metadata.
  *
  * **When to use**
  *
- * Use `OutgoingEnvelope.interrupt` to construct an interrupt envelope for an
+ * Use to construct an interrupt envelope for an
  * in-flight request.
  *
  * @category outgoing
@@ -222,7 +222,7 @@ const neverRpc = Rpc.make("Never", {
  * Control envelopes pass through unchanged. Requests are encoded with their RPC
  * payload schema, reusing the cached encoded request when available.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serialize = <Rpc extends Rpc.Any>(
@@ -245,7 +245,7 @@ export const serialize = <Rpc extends Rpc.Any>(
  *
  * Schema encoding failures are converted to `MalformedMessage`.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serializeEnvelope = <Rpc extends Rpc.Any>(
@@ -264,7 +264,7 @@ export const serializeEnvelope = <Rpc extends Rpc.Any>(
  *
  * The result is a `PartialRequest` suitable for storage or transport.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serializeRequest = <Rpc extends Rpc.Any>(
@@ -290,7 +290,7 @@ export const serializeRequest = <Rpc extends Rpc.Any>(
  * `OutgoingRequest` so the payload can be decoded with the correct RPC schema and
  * context.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const deserializeLocal = <Rpc extends Rpc.Any>(

package/src/unstable/cluster/MessageStorage.ts

@@ -1,27 +1,41 @@
 /**
- * The `MessageStorage` module defines the persistence boundary used by Effect
- * Cluster to store mailbox messages and replies. Storage implementations keep
- * requests, envelopes, and reply chunks durable enough for runners to recover
- * work after restarts, replay unprocessed messages for assigned shards, and
- * deliver replies back to locally registered handlers.
+ * Persistence and reply delivery for Effect Cluster mailboxes.
  *
- * **Common use cases**
+ * `MessageStorage` is the boundary between cluster message delivery and the
+ * storage backend that keeps mailbox state recoverable. Implementations persist
+ * outgoing requests, control envelopes, stream replies, completion replies, and
+ * the indexes needed to find duplicate requests and unprocessed messages for a
+ * runner's assigned shards.
  *
- * - Persist outgoing requests and control envelopes before delivery
- * - Detect duplicate requests by primary key and resume from an existing reply
- * - Query unprocessed messages when shards are assigned to a runner
- * - Store, load, and clear replies for request streams and completions
- * - Reset or clear mailbox state during shard or address lifecycle changes
+ * **Mental model**
+ *
+ * Mailbox delivery has two kinds of state. Durable state lives in the storage
+ * implementation and is used to resume work after restarts or reassignment.
+ * Local state lives in the current process and connects persisted replies to
+ * registered reply handlers. The service combines both: storage methods record
+ * and query durable messages, while handler methods connect replies to the
+ * fibers waiting for them in the current runner.
+ *
+ * **Common tasks**
+ *
+ * - Provide the in-memory storage with {@link layerMemory} for local tests and
+ *   development
+ * - Provide {@link layerNoop} when persistence should be disabled
+ * - Build custom storage from decoded operations with {@link make}
+ * - Build custom storage from encoded operations with {@link makeEncoded}
+ * - Check {@link SaveResult} after saving a request to distinguish new work from
+ *   duplicate request ids
  *
  * **Gotchas**
  *
- * - Implementations should make save and reply operations transactional when
- *   possible so recovery does not observe partial mailbox state
+ * - Reply handlers are process-local; persisted replies may need to be loaded
+ *   again after a runner restart or shard reassignment.
  * - Duplicate detection depends on stable request primary keys and persisted
- *   request ids
- * - Reply handlers are local process state; persisted replies may need to be
- *   loaded again after restarts or reassignment
- * - Concurrent runners must only process messages for shards they currently own
+ *   request ids.
+ * - Storage backends should make save and reply writes transactional when
+ *   possible so recovery never observes partial mailbox state.
+ * - Runners should only process unprocessed messages for shards they currently
+ *   own.
  *
  * @since 4.0.0
  */
@@ -201,7 +215,7 @@ export class MessageStorage extends Context.Service<MessageStorage, {
 export type SaveResult<R extends Rpc.Any> = SaveResult.Success | SaveResult.Duplicate<R>
 
 /**
- * Tagged enum constructor for creating and matching `SaveResult` values.
+ * Constructors and matchers for decoded save results.
  *
  * @category SaveResult
  * @since 4.0.0
@@ -209,7 +223,7 @@ export type SaveResult<R extends Rpc.Any> = SaveResult.Success | SaveResult.Dupl
 export const SaveResult = Data.taggedEnum<SaveResult.Constructor>()
 
 /**
- * Tagged enum constructor for encoded save results returned by encoded storage
+ * Constructors and matchers for encoded save results returned by storage
  * drivers.
  *
  * @category SaveResult
@@ -808,7 +822,7 @@ export const noop: MessageStorage["Service"] = Effect.runSync(make({
  * It stores the encoded envelope, last acknowledged chunk, accumulated replies,
  * and optional delivery time.
  *
- * @category Memory
+ * @category memory
  * @since 4.0.0
  */
 export type MemoryEntry = {
@@ -819,9 +833,9 @@ export type MemoryEntry = {
 }
 
 /**
- * Can be used in tests to simulate a transaction.
+ * Provides a context reference used in tests to simulate a transaction.
  *
- * @category Memory
+ * @category memory
  * @since 4.0.0
  */
 export const MemoryTransaction = Context.Reference<boolean>("effect/cluster/MessageStorage/MemoryTransaction", {
@@ -829,7 +843,7 @@ export const MemoryTransaction = Context.Reference<boolean>("effect/cluster/Mess
 })
 
 /**
- * In-memory message storage driver with inspectable backing state.
+ * Service that provides an in-memory message storage driver with inspectable backing state.
  *
  * **Details**
  *
@@ -837,7 +851,7 @@ export const MemoryTransaction = Context.Reference<boolean>("effect/cluster/Mess
  * maps used to track requests, primary keys, unprocessed envelopes, reply IDs,
  * and the journal.
  *
- * @category Memory
+ * @category memory
  * @since 4.0.0
  */
 export class MemoryDriver extends Context.Service<MemoryDriver>()("effect/cluster/MessageStorage/MemoryDriver", {

package/src/unstable/cluster/Reply.ts

@@ -69,21 +69,26 @@ export type Reply<R extends Rpc.Any> = WithExit<R> | Chunk<R>
 export type Encoded = WithExitEncoded | ChunkEncoded
 
 /**
- * Codec used for reply values that are already in encoded form.
+ * Schema for reply values that are already in encoded form.
  *
  * **Details**
  *
  * Per-RPC payload validation is performed by `Reply(rpc)`.
  *
- * @category models
+ * @category schemas
  * @since 4.0.0
  */
 export const Encoded: Schema.Codec<Encoded> = Schema.Any as any
 
 /**
- * A cluster reply paired with the RPC definition and service context required to
+ * Represents a cluster reply paired with the RPC definition and service context required to
  * serialize it for transport.
  *
+ * **When to use**
+ *
+ * Use to carry a runtime reply together with the RPC schema and services needed
+ * to encode it for storage or transport.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -171,8 +176,8 @@ export interface ChunkEncoded {
 const schemaCache = new WeakMap<Rpc.Any, Schema.Top>()
 
 /**
- * A streaming RPC reply chunk for a request, carrying a non-empty batch of success
- * values together with the reply id and sequence number.
+ * Represents a streaming RPC reply chunk for a request, carrying a non-empty
+ * batch of success values together with the reply id and sequence number.
  *
  * @category models
  * @since 4.0.0
@@ -290,9 +295,14 @@ export class Chunk<R extends Rpc.Any> extends Data.TaggedClass("Chunk")<{
 }
 
 /**
- * A terminal RPC reply for a request, carrying the final `Exit` for the remote
+ * Represents a terminal RPC reply for a request, carrying the final `Exit` for the remote
  * call.
  *
+ * **When to use**
+ *
+ * Use to represent the final success, typed failure, defect, or interruption
+ * for a clustered RPC request.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -416,7 +426,7 @@ export const Reply = <R extends Rpc.Any>(
  * reply's RPC schema and context and refailing encoding errors as
  * `MalformedMessage`.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serialize = <R extends Rpc.Any>(
@@ -436,7 +446,7 @@ export const serialize = <R extends Rpc.Any>(
  * `None` when no reply has been received and refailing encoding errors as
  * `MalformedMessage`.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serializeLastReceived = <R extends Rpc.Any>(

package/src/unstable/cluster/Runner.ts

@@ -1,27 +1,41 @@
 /**
- * The `Runner` module defines the membership record used by the unstable
- * cluster runtime to describe a process that can host entity shards.
+ * Cluster runner metadata for processes that can host entity shards.
  *
- * A runner combines the network address used by other runners to reach it, the
- * shard groups it participates in, and a relative weight used when the sharding
- * service assigns shards across the healthy runners in each group.
+ * A {@link Runner} combines the stable {@link RunnerAddress} used to contact a
+ * process, the shard groups that process participates in, and the relative
+ * weight used when the sharding service distributes shards across healthy
+ * runners.
+ *
+ * **Mental model**
+ *
+ * `Runner` is cluster membership data, not a running process handle. The value
+ * is persisted, exchanged, encoded, and compared by cluster services so they can
+ * decide where entity shards may live. The address identifies the runner, groups
+ * limit the shard pools it can join, and weight changes how much ownership it
+ * receives relative to the other healthy runners in the same group.
  *
  * **Common tasks**
  *
- * - Construct the runner registered by the local `Sharding` layer
- * - Persist or exchange runner metadata through `RunnerStorage`
- * - Encode and decode runner values at cluster transport or storage boundaries
+ * - Construct runner metadata with {@link make}.
+ * - Encode and decode runner values at cluster transport or storage boundaries.
+ * - Persist or exchange runner records through cluster runner storage.
  * - Tune shard distribution by adjusting the runner's group membership and
- *   relative weight
+ *   relative weight.
  *
  * **Gotchas**
  *
  * - Runner addresses must be stable and unique while a runner is registered,
  *   because they identify the owner used for routing and shard locks.
- * - Weights are relative within each shard group; changing weights or groups can
- *   rebalance shard ownership as the cluster refreshes its runner view.
- * - Runner equality and hashing are based on address and weight, so compare
- *   `groups` explicitly when group membership is the important distinction.
+ * - Weights are relative inside each shard group; changing a weight or group can
+ *   rebalance shard ownership when the cluster refreshes its runner view.
+ * - Equality and hashing use address and weight. Compare `groups` explicitly
+ *   when group membership is the important distinction.
+ *
+ * **See also**
+ *
+ * - {@link Runner}
+ * - {@link RunnerAddress}
+ * - {@link make}
  *
  * @since 4.0.0
  */
@@ -34,7 +48,7 @@ import { RunnerAddress } from "./RunnerAddress.ts"
 const TypeId = "~effect/cluster/Runner"
 
 /**
- * A cluster runner that can host entities.
+ * Represents a cluster runner that can host entities.
  *
  * **Details**
  *
@@ -118,6 +132,25 @@ export class Runner extends Schema.Class<Runner>(TypeId)({
  * Constructs a `Runner` from its network address, shard groups, and relative
  * shard-assignment weight.
  *
+ * **When to use**
+ *
+ * Use to build runner metadata from an existing `RunnerAddress`, shard groups,
+ * and relative weight when registering or exchanging a cluster runner.
+ *
+ * **Details**
+ *
+ * The `groups` array lists the shard groups the runner can host. During shard
+ * assignment, the runner's address is added to each group's hash ring with
+ * `weight` as its relative weight.
+ *
+ * **Gotchas**
+ *
+ * This helper constructs the value without runtime schema validation, so only
+ * pass trusted `RunnerAddress`, `groups`, and `weight` values.
+ *
+ * @see {@link Runner} for the value created by this helper
+ * @see {@link RunnerAddress} for the network address accepted in `props.address`
+ *
  * @category constructors
  * @since 4.0.0
  */

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
  */
@@ -26,7 +43,13 @@ import * as Schema from "../../Schema.ts"
 const TypeId = "~effect/cluster/RunnerAddress"
 
 /**
- * Network address of a cluster runner, identified by host and port.
+ * Represents the network address of a cluster runner, identified by host and
+ * port.
+ *
+ * **When to use**
+ *
+ * Use to represent the host and port that identify a runner in cluster routing,
+ * registration, and health checks.
  *
  * @category models
  * @since 4.0.0
@@ -91,6 +114,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
  */
@@ -50,11 +67,11 @@ export class RunnerHealth extends Context.Service<
 >()("effect/cluster/RunnerHealth") {}
 
 /**
- * A layer which will **always** consider a Runner healthy.
+ * Layer that always considers a runner healthy.
  *
  * **When to use**
  *
- * This is useful for testing.
+ * Use when tests or local development do not need active runner health checks.
  *
  * @category layers
  * @since 4.0.0
@@ -91,7 +108,7 @@ export const makePing: Effect.Effect<
 })
 
 /**
- * A layer which will ping a Runner directly to check if it is healthy.
+ * Layer that pings runners directly to check whether they are healthy.
  *
  * @category layers
  * @since 4.0.0
@@ -129,7 +146,7 @@ export const makeK8s = Effect.fnUntraced(function*(options?: {
 })
 
 /**
- * A layer which checks Kubernetes pod readiness to determine whether a runner is
+ * Layer that checks Kubernetes pod readiness to determine whether a runner is
  * healthy.
  *
  * **Details**

package/src/unstable/cluster/RunnerServer.ts

@@ -46,8 +46,8 @@ import { ShardingConfig } from "./ShardingConfig.ts"
 const constVoid = constant(Effect.void)
 
 /**
- * Layer of RPC handlers for the runner protocol, forwarding ping, notify, effect,
- * stream, and envelope requests to `Sharding` and `MessageStorage`.
+ * Layer that handles runner protocol RPCs by forwarding requests to `Sharding`
+ * and `MessageStorage`.
  *
  * @category layers
  * @since 4.0.0
@@ -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
  */
@@ -173,7 +187,8 @@ export const layer: Layer.Layer<
 }).pipe(Layer.provide(layerHandlers))
 
 /**
- * A `RunnerServer` layer that includes the `Runners` & `Sharding` clients.
+ * Layer that provides `RunnerServer` together with `Runners` and `Sharding`
+ * clients.
  *
  * @category layers
  * @since 4.0.0
@@ -197,7 +212,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