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

package/src/unstable/cluster/ClusterSchema.ts

@@ -1,29 +1,46 @@
 /**
- * The `ClusterSchema` module defines the schema annotations used by Effect
- * Cluster protocols. These annotations attach cluster-specific behavior to
- * RPCs and entities without changing the request or response schemas
- * themselves.
+ * The `ClusterSchema` module collects the annotations that add cluster behavior
+ * to RPC protocols and entity definitions. These annotations describe how
+ * requests are persisted, handled in transactions, interrupted, traced, and
+ * routed to shard groups without changing the request or response schema.
+ *
+ * **Mental model**
+ *
+ * - An annotation is protocol metadata read by the cluster runtime.
+ * - Static annotations apply to every request covered by the annotated RPC or
+ *   entity.
+ * - {@link Dynamic} can adjust server-side annotations from the decoded request
+ *   that is already part of the protocol.
  *
  * **Common tasks**
  *
- * - Mark requests as persisted so mailbox storage can replay them after
- *   interruption or restart
- * - Run server-side handling inside a storage transaction when durable state
- *   and SQL updates must commit together
- * - Control whether client sending, server handling, or both are treated as
- *   uninterruptible
- * - Route entity ids into shard groups
- * - Disable client tracing for internal protocols such as cron dispatch
- * - Derive per-request annotations from the encoded request with {@link Dynamic}
- *
- * **Protocol notes**
- *
- * Cluster transports serialize the RPC payloads, not arbitrary runtime
- * annotation values. Prefer static, deterministic annotations, and use
- * {@link Dynamic} when a persisted or transactional decision depends on the
- * request value that is already part of the protocol. Persisted requests require
- * message storage support, and shard group selection must remain stable for a
- * given entity id so routing is consistent across cluster members.
+ * - Mark requests for durable mailbox storage with {@link Persisted}.
+ * - Wrap server handling and storage work in the configured storage transaction
+ *   with {@link WithTransaction}.
+ * - Decide whether client sending, server handling, or both ignore interruption
+ *   with {@link Uninterruptible}.
+ * - Route entity ids into shard groups with {@link ShardGroup}.
+ * - Disable client tracing for internal or high-volume protocols with
+ *   {@link ClientTracingEnabled}.
+ * - Derive request annotations from the request value with {@link Dynamic}.
+ *
+ * **Gotchas**
+ *
+ * - Persisted requests require message storage that can save mailbox messages
+ *   and replies.
+ * - {@link WithTransaction} only has transactional behavior when the configured
+ *   storage layer implements transactions.
+ * - Shard group functions must be deterministic for the same entity id across
+ *   all runners that share a cluster.
+ * - {@link Dynamic} affects entity-side request handling, not the generated
+ *   client.
+ *
+ * **See also**
+ *
+ * - {@link Persisted}, {@link WithTransaction}, and {@link Uninterruptible} for
+ *   delivery and handling behavior.
+ * - {@link ShardGroup} for shard-group selection.
+ * - {@link Dynamic} for deriving annotations from a request.
  *
  * @since 4.0.0
  */
@@ -49,8 +66,23 @@ export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchem
 })
 
 /**
- * Whether to wrap the request with a storage transaction, so sql queries are
- * committed atomically.
+ * Annotation that marks whether request handling should be wrapped in the
+ * configured message storage transaction.
+ *
+ * **When to use**
+ *
+ * Use when a request needs server-side handling or storage work wrapped in the
+ * storage transaction.
+ *
+ * **Details**
+ *
+ * The default value is `false`. When `true`, entity handling wraps server
+ * writes with the configured storage transaction.
+ *
+ * **Gotchas**
+ *
+ * This annotation has transactional behavior only when the configured
+ * `MessageStorage` implements it.
  *
  * @category annotations
  * @since 4.0.0
@@ -82,6 +114,13 @@ export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
  * Returns whether the `Uninterruptible` annotation applies to server-side
  * request handling for the provided context.
  *
+ * **Details**
+ *
+ * Returns `true` only when `Uninterruptible` is `true` or `"server"`.
+ *
+ * @see {@link Uninterruptible} for the annotation values interpreted by this helper
+ * @see {@link isUninterruptibleForClient} for the client-side counterpart
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -94,6 +133,19 @@ export const isUninterruptibleForServer = (context: Context.Context<never>): boo
  * Returns whether the `Uninterruptible` annotation applies to client-side
  * request handling for the provided context.
  *
+ * **When to use**
+ *
+ * Use when client-side cluster request handling needs to decide whether an
+ * interrupt should be ignored.
+ *
+ * **Details**
+ *
+ * Returns `true` when `Uninterruptible` is `true` or `"client"`, and `false`
+ * for `"server"` or the default `false`.
+ *
+ * @see {@link Uninterruptible} for the annotation values interpreted by this helper
+ * @see {@link isUninterruptibleForServer} for the server-side counterpart
+ *
  * @category annotations
  * @since 4.0.0
  */

package/src/unstable/cluster/Entity.ts

@@ -447,6 +447,23 @@ export const fromRpcGroup = <const Type extends string, Rpcs extends Rpc.Any>(
  * Creates a new `Entity` of the specified `type` which will accept messages
  * that adhere to the provided schemas.
  *
+ * **When to use**
+ *
+ * Use to define a cluster entity from individual `Rpc` definitions, giving the
+ * cluster runtime a typed protocol for handlers and per-entity clients.
+ *
+ * **Details**
+ *
+ * The `type` argument is stored as the entity `EntityType`, and the RPC array
+ * is grouped into the entity's `protocol`.
+ *
+ * **Gotchas**
+ *
+ * RPC tags should be unique within the array. If multiple definitions use the
+ * same tag, the resulting protocol keeps the later definition for that tag.
+ *
+ * @see {@link fromRpcGroup} for creating an entity from an existing `RpcGroup`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -489,7 +506,7 @@ export class CurrentRunnerAddress extends Context.Service<
  *
  * **When to use**
  *
- * Use it to complete an entity request by succeeding, failing, failing with a
+ * Use when you use it to complete an entity request by succeeding, failing, failing with a
  * cause, or supplying an explicit `Exit`.
  *
  * @category Replier

package/src/unstable/cluster/EntityAddress.ts

@@ -77,6 +77,25 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
 /**
  * Constructs an `EntityAddress` from a shard ID, entity type, and entity ID.
  *
+ * **When to use**
+ *
+ * Use to create the routing target for a known entity type and entity id after
+ * resolving that id to the `ShardId` assigned by the entity's shard group.
+ *
+ * **Details**
+ *
+ * The returned `EntityAddress` stores the supplied `shardId`, `entityType`, and
+ * `entityId`. Equality and hashing include all three fields.
+ *
+ * **Gotchas**
+ *
+ * `make` does not choose the shard for an entity. Use the same shard group
+ * logic as the entity definition; a different `shardId` makes a different
+ * address even when the entity type and entity id match.
+ *
+ * @see {@link EntityAddress} for the equality, hashing, and string formatting behavior of constructed addresses
+ * @see {@link ShardId} for the shard identifier included in the address
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/EntityId.ts

@@ -1,12 +1,32 @@
 /**
- * The `EntityId` module provides a branded string identifier for addressing a
- * specific entity instance inside the cluster. Entity ids are commonly used as
- * stable routing keys when sending messages to an entity, looking up its state,
- * or deriving the shard responsible for that entity.
+ * The `EntityId` module defines the branded string used to identify one entity
+ * instance within an entity type. The value is the routing key that sharding
+ * hashes, stores in entity addresses, and uses when sending messages to a
+ * running entity.
  *
- * Because routing is based on the exact string value, choose ids that are
- * deterministic, normalized, and unique within the entity type you are
- * addressing. Avoid display names or other values that may change over time.
+ * **Mental model**
+ *
+ * - An entity id is a stable string with a brand; at runtime it is still the
+ *   original string
+ * - Uniqueness is scoped by entity type, so two different entity types may use
+ *   the same id without addressing the same entity
+ * - Routing depends on the exact string value, including casing and
+ *   normalization
+ *
+ * **Common tasks**
+ *
+ * - Brand trusted ids with {@link make} before passing them to cluster APIs
+ * - Use the {@link EntityId} schema when decoding or encoding ids at
+ *   boundaries
+ * - Store ids alongside entity type and shard id when building entity
+ *   addresses
+ *
+ * **Gotchas**
+ *
+ * - {@link make} does not validate, normalize, or ensure uniqueness
+ * - Avoid display names, emails that may change, or values with inconsistent
+ *   casing or whitespace
+ * - Changing an id changes the shard routing target for that entity
  *
  * @since 4.0.0
  */
@@ -31,6 +51,23 @@ export type EntityId = typeof EntityId.Type
 /**
  * Brands a string as an `EntityId`.
  *
+ * **When to use**
+ *
+ * Use to turn a trusted, stable entity routing key into an `EntityId` before
+ * passing it to cluster APIs.
+ *
+ * **Details**
+ *
+ * The branded value is the original string at runtime.
+ *
+ * **Gotchas**
+ *
+ * `make` does not validate, normalize, or make the value unique. Choose
+ * deterministic strings because cluster routing hashes the exact entity id
+ * value.
+ *
+ * @see {@link EntityId} for the schema that validates and encodes branded entity identifiers
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/EntityType.ts

@@ -40,6 +40,25 @@ export type EntityType = typeof EntityType.Type
 /**
  * Brands a string as an `EntityType`.
  *
+ * **When to use**
+ *
+ * Use to brand a stable entity family name before passing it to cluster APIs
+ * that require an `EntityType`, such as entity addresses.
+ *
+ * **Details**
+ *
+ * The returned value is the same runtime string with the `EntityType` brand
+ * applied by TypeScript.
+ *
+ * **Gotchas**
+ *
+ * `make` only applies the brand at the type level; it does not validate,
+ * normalize, or check uniqueness. Use the `EntityType` schema when you need
+ * schema-based decoding or validation, and keep names stable because the exact
+ * string participates in routing identity.
+ *
+ * @see {@link EntityType} for schema-based decoding, validation, and encoding of entity type names
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/HttpRunner.ts

@@ -1,26 +1,38 @@
 /**
- * The `HttpRunner` module wires cluster runner RPCs to HTTP transports. It
- * provides client protocol layers for contacting runners over HTTP or
- * WebSocket, server-side HTTP effects for exposing runner RPC handlers, and
- * complete layers that install those routes into an `HttpRouter`.
+ * HTTP and WebSocket transport layers for cluster runner RPCs.
+ *
+ * Runner nodes communicate through the `Runners.Rpcs` protocol. This module
+ * connects that protocol to HTTP transports by providing client protocols for
+ * dialing runner addresses, HTTP effects for serving runner RPC handlers, and
+ * complete layers that install runner routes into an `HttpRouter`.
+ *
+ * **Mental model**
+ *
+ * Runner communication has two sides: a client protocol that knows how to turn a
+ * runner address into an RPC connection, and a server route that exposes the
+ * runner RPC handlers. The complete layers provide both sides with matching
+ * defaults, while the `Options` and `ClientOnly` variants let applications wire
+ * only the pieces they need.
  *
  * **Common tasks**
  *
- * - Serve runner RPC routes with {@link layerHttp} or {@link layerWebsocket}
- * - Configure client-only runner communication with {@link layerHttpClientOnly}
+ * - Serve runners over HTTP with {@link layerHttp} or {@link layerHttpOptions}
+ * - Serve runners over WebSocket with {@link layerWebsocket} or
+ *   {@link layerWebsocketOptions}
+ * - Configure clients without serving routes with {@link layerHttpClientOnly}
  *   or {@link layerWebsocketClientOnly}
- * - Use custom route paths with {@link layerHttpOptions},
- *   {@link layerWebsocketOptions}, {@link layerClientProtocolHttp}, or
+ * - Build custom client protocols with {@link layerClientProtocolHttp} or
  *   {@link layerClientProtocolWebsocket}
  *
- * **Transport gotchas**
+ * **Gotchas**
  *
- * - Client protocol paths are appended to each runner address when building the
- *   target URL
- * - `https: true` switches HTTP clients from `http` to `https`, and WebSocket
+ * - Server route paths and client protocol paths must match
+ * - `https: true` switches HTTP clients from `http` to `https` and WebSocket
  *   clients from `ws` to `wss`
- * - The default complete layers serve and connect at `/`; use the `Options`
- *   variants when your runner routes live under a different path
+ * - The complete layers serve and connect at `/`; use the `Options` variants
+ *   when runner routes live under another path
+ * - {@link toHttpEffect} and {@link toHttpEffectWebsocket} expose raw HTTP
+ *   effects for adapters that do not use `HttpRouter.serve`
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/K8sHttpClient.ts

@@ -1,21 +1,40 @@
 /**
- * The `K8sHttpClient` module provides an HTTP client service for talking to the
- * Kubernetes API from code running inside a cluster.
+ * HTTP client support for talking to the Kubernetes API from code running
+ * inside a cluster. The module builds a `K8sHttpClient` service on top of the
+ * shared HTTP client, points requests at the in-cluster API endpoint, and uses
+ * the mounted service-account token when one is available.
  *
- * It configures requests for the in-cluster service endpoint, attaches the
- * mounted service-account token when present, and exposes helpers for common
- * cluster tasks such as discovering running pods by namespace or label selector
- * and creating scoped pods that are cleaned up automatically.
+ * **Mental model**
+ *
+ * - {@link layer} adapts an existing `HttpClient` so relative requests target
+ *   `https://kubernetes.default.svc/api`.
+ * - {@link K8sHttpClient} is the service tag consumed by the cluster helpers in
+ *   this module.
+ * - {@link makeGetPods} returns a cached effect that lists running pods and
+ *   indexes them by pod IP address.
+ * - {@link makeCreatePod} returns a scoped creator that creates a pod when it
+ *   is missing, waits for readiness, and deletes it when the scope closes.
+ * - {@link Pod} and {@link PodStatus} model only the status fields needed by
+ *   these helpers.
+ *
+ * **Common tasks**
+ *
+ * - Discover running pods in a namespace or behind a label selector.
+ * - Create short-lived pods for cluster workflows and let scope finalization
+ *   clean them up.
+ * - Reuse the configured `K8sHttpClient` for Kubernetes API calls that share
+ *   the same in-cluster endpoint, token, status filtering, and retry policy.
  *
  * **Gotchas**
  *
- * - The default layer targets `https://kubernetes.default.svc/api`, so it is
- *   intended for workloads with Kubernetes DNS and service-account mounts.
- * - Pod discovery is keyed by pod IP address and only includes pods whose phase
- *   is `Running`; callers should choose selectors that match the intended
- *   service topology.
- * - Network policies, RBAC, and service-account token availability can all
- *   prevent the client from reaching or authorizing with the Kubernetes API.
+ * - The default layer assumes Kubernetes DNS and the standard service-account
+ *   mount path used by in-cluster workloads.
+ * - Pod discovery filters to `status.phase=Running`; pods without the expected
+ *   status shape fail schema decoding.
+ * - Pod maps are keyed by pod IP address, so selectors should match the service
+ *   topology the caller actually wants to route to.
+ * - RBAC, network policies, and missing service-account tokens can still block
+ *   requests even when the layer is present.
  *
  * @since 4.0.0
  */

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

@@ -181,7 +181,7 @@ export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("Outgoi
  *
  * **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

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
  */

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
  */
@@ -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
  */