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

package/dist/unstable/cluster/index.d.ts

@@ -2,944 +2,154 @@
  * @since 4.0.0
  */
 /**
- * The `ClusterCron` module provides a small integration between cron schedules
- * and cluster sharding. It turns a `Cron.Cron` schedule into a `Layer` that
- * coordinates one recurring job across a cluster by registering a singleton for
- * the initial scheduling step and a persisted entity message for each run.
- *
- * This is useful for distributed maintenance work such as periodic cleanup,
- * reconciliation, report generation, cache refreshes, or polling external
- * systems where the job should be owned by the cluster rather than by every
- * runner independently.
- *
- * **Mental model**
- *
- * - {@link make} registers a named cluster cron job as a layer
- * - a singleton schedules the first run for the selected shard group
- * - each run is delivered as a persisted entity message at its scheduled time
- * - after a run exits, the handler schedules the next occurrence
- * - stale runs can be skipped with `skipIfOlderThan`
- *
- * **Gotchas**
- *
- * - Job effects should be idempotent because persisted messages, retries, and
- *   runner failover are part of normal distributed execution.
- * - By default, the next run is calculated from the current time after the
- *   handler exits; use `calculateNextRunFromPrevious` when preserving the
- *   schedule cadence is more important than catching up from delays.
- * - Long outages can produce old scheduled messages; keep `skipIfOlderThan`
- *   aligned with the job's business semantics.
- *
  * @since 4.0.0
  */
 export * as ClusterCron from "./ClusterCron.ts";
 /**
- * The `ClusterError` module defines the typed error values used by the
- * unstable cluster runtime when routing messages to entities, coordinating
- * runners, and persisting mailbox work.
- *
- * These errors are useful when implementing cluster transports, runner
- * supervision, mailbox storage, and entity request handling. They make common
- * distributed-system failures explicit: a message may reach a runner that no
- * longer owns the entity, a runner may be unavailable or unregistered, a
- * payload may fail to decode, persistence may fail, a mailbox may be at
- * capacity, or an envelope may already be in progress.
- *
- * **Gotchas**
- *
- * - Entity ownership and runner availability can change while messages are in
- *   flight, so routing errors should generally be treated as retryable or
- *   recoverable by higher-level cluster logic.
- * - `MalformedMessage` points to a schema/serialization boundary failure,
- *   while `PersistenceError` preserves failures from durable mailbox storage.
- * - `AlreadyProcessingMessage` protects an entity mailbox from processing the
- *   same envelope concurrently.
- *
  * @since 4.0.0
  */
 export * as ClusterError from "./ClusterError.ts";
 /**
- * The `ClusterMetrics` module defines the standard metrics emitted by the
- * unstable cluster runtime. These gauges track the shape and health of a
- * running cluster from the perspective of runners, entities, singletons, and
- * shard ownership.
- *
- * **Common tasks**
- *
- * - Monitor how many entity instances and singleton processes are active on a
- *   runner
- * - Track registered runners and the subset currently considered healthy
- * - Observe shard distribution across runners during startup, rebalancing, and
- *   failover
- *
- * **Gotchas**
- *
- * - Runner-local gauges such as {@link entities}, {@link singletons}, and
- *   {@link shards} describe the current runner, so aggregate them carefully in
- *   dashboards
- * - Cluster-wide gauges such as {@link runners} and {@link runnersHealthy}
- *   reflect the runtime's current view, which may lag briefly during membership
- *   changes or failure detection
- *
  * @since 4.0.0
  */
 export * as ClusterMetrics from "./ClusterMetrics.ts";
 /**
- * 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.
- *
- * **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.
- *
  * @since 4.0.0
  */
 export * as ClusterSchema from "./ClusterSchema.ts";
 /**
- * The cluster workflow engine runs durable workflows on top of cluster sharding
- * and message storage. It adapts `WorkflowEngine.WorkflowEngine` so workflow
- * executions, activities, deferred completions, resumes, interrupts, and durable
- * clock wakeups are represented as persisted cluster entity messages.
- *
- * **Common tasks**
- *
- * - Provide a workflow engine for services that already use cluster sharding
- * - Execute workflows by stable execution id and poll their persisted result
- * - Resume suspended workflows after activities, deferreds, or durable clock wakeups
- * - Interrupt workflow executions and propagate resume signals to parent workflows
- *
- * **Gotchas**
- *
- * - Workflow names and execution ids determine the cluster entity address used
- *   for persistence, so they must remain stable across deploys
- * - Activities are persisted by activity name and attempt; retries and suspended
- *   activity resumes depend on those primary keys
- * - Durable clock wakeups are scheduled through a separate clock entity and are
- *   cleared when an interrupted workflow stops waiting
- *
  * @since 4.0.0
  */
 export * as ClusterWorkflowEngine from "./ClusterWorkflowEngine.ts";
 /**
- * The `DeliverAt` module defines the protocol used by cluster message payloads
- * that carry their own scheduled delivery time. A value implements the protocol
- * by exposing a method at the `DeliverAt` symbol that returns the target
- * `DateTime`.
- *
- * **Common tasks**
- *
- * - Mark a message payload as deliverable at a specific time by implementing
- *   {@link DeliverAt}
- * - Check whether an arbitrary value carries a scheduled delivery time with
- *   {@link isDeliverAt}
- * - Convert a scheduled delivery time to epoch milliseconds with
- *   {@link toMillis}
- *
- * **Gotchas**
- *
- * - The protocol records the requested delivery instant; cluster infrastructure
- *   may still deliver later because of clock skew, queue latency, or worker
- *   availability
- * - Values that do not implement the symbol method are treated as unscheduled;
- *   {@link toMillis} returns `null` for those values
- *
  * @since 4.0.0
  */
 export * as DeliverAt from "./DeliverAt.ts";
 /**
- * The `Entity` module defines sharded, addressable actors for Effect Cluster.
- * An entity type pairs a stable entity name with an RPC protocol and describes
- * how requests for individual entity ids are routed to shard groups and
- * runners.
- *
- * **Mental model**
- *
- * - An `Entity` is the cluster-facing definition for one logical actor type
- * - Each entity id maps deterministically to a shard group and shard id
- * - Clients are created per entity id and send typed RPC messages through the
- *   cluster sharding layer
- * - Server layers register handlers or mailbox processors for the entity type
- *
- * **Common tasks**
- *
- * - Define an entity protocol with RPCs and create an entity with {@link make}
- * - Send messages to a specific entity id with {@link Entity.client}
- * - Register typed RPC handlers with {@link Entity.toLayer}
- * - Process envelopes directly with {@link Entity.toLayerQueue}
- * - Access the current entity or runner address with {@link CurrentAddress} and
- *   {@link CurrentRunnerAddress}
- *
- * **Gotchas**
- *
- * - Entity ids are part of routing: changing id formats can move work to
- *   different shards
- * - Entity type names should be stable and unique within a cluster deployment
- * - Mailbox capacity and concurrency determine back pressure and duplicate
- *   processing behavior
- * - Persistence, mailbox, and already-processing failures are surfaced through
- *   the generated clients
- *
  * @since 4.0.0
  */
 export * as Entity from "./Entity.ts";
 /**
- * The `EntityAddress` module defines the value used to locate an entity within
- * a cluster. An address combines the entity type, entity id, and shard id so
- * messages, persisted envelopes, workflow executions, and entity managers can
- * agree on the same routing target.
- *
- * **Common tasks**
- *
- * - Build an address after resolving an entity id to a shard with `Sharding`
- * - Attach an address to cluster envelopes and persisted messages
- * - Compare or hash addresses when tracking active or resuming entities
- *
- * **Gotchas**
- *
- * - The shard id is part of the address identity; the same entity type and id
- *   on a different shard is a different address.
- * - Entity ids should be routed through the same shard group logic used by the
- *   entity definition so messages are sent to the runner that owns the shard.
- *
  * @since 4.0.0
  */
 export * as EntityAddress from "./EntityAddress.ts";
 /**
- * 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.
- *
- * 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.
- *
  * @since 4.0.0
  */
 export * as EntityId from "./EntityId.ts";
 /**
- * The `EntityProxy` module derives external RPC and HTTP API surfaces from a
- * clustered {@link Entity.Entity}. It is used when callers should communicate
- * with entities through ordinary RPC clients or HTTP routes while the cluster
- * runtime keeps responsibility for locating, routing, and delivering messages
- * to the entity instance identified by `entityId`.
- *
- * **Common tasks**
- *
- * - Derive an `RpcGroup` from an entity with {@link toRpcGroup}
- * - Derive an `HttpApiGroup` from an entity with {@link toHttpApiGroup}
- * - Expose both request/response calls and discard variants for fire-and-forget
- *   delivery
- *
- * **Gotchas**
- *
- * - Proxy RPC payloads wrap the original RPC payload with an `entityId`; HTTP
- *   endpoints place the same identifier in the route path.
- * - Generated RPC names are prefixed with the entity type, while HTTP endpoint
- *   paths are based on lower-cased RPC tags.
- * - Proxy errors include cluster delivery errors such as mailbox saturation,
- *   duplicate in-flight messages, and persistence failures.
- *
  * @since 4.0.0
  */
 export * as EntityProxy from "./EntityProxy.ts";
 /**
- * The `EntityProxyServer` module provides server-side layers for exposing
- * clustered entities through proxy APIs. It connects proxy requests to an
- * entity client, extracts the target `entityId`, and forwards the payload to
- * the matching entity RPC method.
- *
- * **Common tasks**
- *
- * - Serve an entity proxy over an HTTP API group with {@link layerHttpApi}
- * - Serve the RPC group produced by an entity proxy with {@link layerRpcHandlers}
- * - Route both normal calls and discard calls to the same underlying entity
- *   method
- *
- * **Gotchas**
- *
- * - HTTP proxy endpoints expect the `entityId` path parameter to identify the
- *   target entity instance
- * - RPC proxy handlers use tags prefixed with the entity type, matching the
- *   group generated by `EntityProxy.toRpcGroup`
- * - Both layers require `Sharding` and the entity RPC server services in the
- *   environment so requests can be routed to the owning shard
- *
  * @since 4.0.0
  */
 export * as EntityProxyServer from "./EntityProxyServer.ts";
 /**
- * The `EntityResource` module provides helpers for acquiring resources inside a
- * cluster entity and keeping them available across entity restarts. It is useful
- * for long-lived resources tied to an entity address, such as external
- * processes, network clients, Kubernetes Pods, or other handles that should not
- * be torn down during routine shard movement.
- *
- * **Common tasks**
- *
- * - Create a reusable entity-scoped resource with {@link make}
- * - Keep an entity alive while the resource is acquired
- * - Explicitly release the resource with `EntityResource.close`
- * - Attach cleanup work to the resource close scope with {@link CloseScope}
- * - Create and manage a Kubernetes Pod resource with {@link makeK8sPod}
- *
- * **Lifecycle gotchas**
- *
- * - Resources are retained by an `RcRef` and are only fully released after
- *   `idleTimeToLive` expires or `close` is called
- * - The default idle time to live is infinite, so resources remain alive until
- *   explicitly closed
- * - `CloseScope` is separate from the caller scope and is not closed by entity
- *   restarts, shard movement, or node shutdown finalization
- *
  * @since 4.0.0
  */
 export * as EntityResource from "./EntityResource.ts";
 /**
- * The `EntityType` module defines the branded string used to identify a kind of
- * entity in an Effect cluster. Entity type names are part of the cluster routing
- * identity: they distinguish one family of entities from another before an
- * individual entity id is considered.
- *
- * **Common tasks**
- *
- * - Declare the stable name for an entity family handled by a cluster service
- * - Brand a string literal as an {@link EntityType} with {@link make}
- * - Validate or encode entity type names with the {@link EntityType} schema
- *
- * **Gotchas**
- *
- * - Entity type names should be stable and unique within the cluster because
- *   changing them changes where entity messages are routed
- * - The entity type name identifies the entity family, not a specific entity
- *   instance; combine it with the entity id at the call site that routes work
- *
  * @since 4.0.0
  */
 export * as EntityType from "./EntityType.ts";
 /**
- * The `Envelope` module defines the transport messages exchanged by Effect
- * cluster entities while processing RPC requests. Envelopes wrap decoded
- * request payloads with routing metadata, trace context, and request ids, and
- * also model delivery-control messages such as streamed-reply acknowledgements
- * and request interrupts.
- *
- * **Common use cases**
- *
- * - Construct a runtime request envelope with {@link makeRequest}
- * - Decode or encode envelopes crossing a network or durable queue with {@link PartialJson}
- * - Batch encoded envelopes with {@link PartialArray}
- * - Detect envelope values at runtime with {@link isEnvelope}
- * - Build storage keys for keyed request payloads with {@link primaryKey}
- *
- * **Serialization and delivery notes**
- *
- * Request envelopes are decoded in two phases: the envelope metadata is parsed
- * first, while the RPC payload remains `unknown` until the receiving side knows
- * the target RPC schema. Snowflake identifiers are encoded as strings for JSON
- * transport, and acknowledgement / interrupt envelopes carry the original
- * request id so delivery protocols can correlate control messages with the
- * in-flight request.
- *
  * @since 4.0.0
  */
 export * as Envelope from "./Envelope.ts";
 /**
- * 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`.
- *
- * **Common tasks**
- *
- * - Serve runner RPC routes with {@link layerHttp} or {@link layerWebsocket}
- * - Configure client-only runner communication with {@link layerHttpClientOnly}
- *   or {@link layerWebsocketClientOnly}
- * - Use custom route paths with {@link layerHttpOptions},
- *   {@link layerWebsocketOptions}, {@link layerClientProtocolHttp}, or
- *   {@link layerClientProtocolWebsocket}
- *
- * **Transport 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
- *   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
- *
  * @since 4.0.0
  */
 export * as HttpRunner from "./HttpRunner.ts";
 /**
- * The `K8sHttpClient` module provides an HTTP client service for talking to the
- * Kubernetes API from code running inside a cluster.
- *
- * 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.
- *
- * **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.
- *
  * @since 4.0.0
  */
 export * as K8sHttpClient from "./K8sHttpClient.ts";
 /**
- * The `MachineId` module provides the branded integer identifier used to
- * distinguish cluster runners when generating distributed ids and coordinating
- * runner state.
- *
- * **When to use**
- *
- * - 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
- *
- * **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
- *
  * @since 4.0.0
  */
 export * as MachineId from "./MachineId.ts";
 /**
- * The cluster `Message` module defines the in-memory shapes used while moving
- * requests and control envelopes between callers, durable storage, transports,
- * and entity runners.
- *
- * **Common use cases**
- *
- * - Representing outgoing entity requests before they are stored or sent
- * - Reconstructing incoming requests that runners read from storage or transport
- * - Converting outgoing messages into local, in-process deliveries
- * - Serializing request payloads with the associated RPC schema and context
- * - Passing control envelopes such as acknowledgements and interrupts through
- *   without payload decoding
- *
- * **Gotchas**
- *
- * - Requests can exist in decoded local form or encoded persisted form; choose
- *   `IncomingLocal` / `OutgoingRequest` for local delivery and `IncomingRequest`
- *   / `Envelope.PartialRequest` for storage or transport boundaries.
- * - Request payloads must be encoded and decoded with the matching RPC payload
- *   schema and service context, otherwise failures are surfaced as
- *   `MalformedMessage`.
- * - Delivery state such as the last sent or received reply is carried alongside
- *   messages so retries and persisted replies can preserve cluster semantics.
- *
  * @since 4.0.0
  */
 export * as Message from "./Message.ts";
 /**
- * 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.
- *
- * **Common use cases**
- *
- * - 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
- *
- * **Gotchas**
- *
- * - Implementations should make save and reply operations transactional when
- *   possible so recovery does not observe partial mailbox state
- * - 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
- *
  * @since 4.0.0
  */
 export * as MessageStorage from "./MessageStorage.ts";
 /**
- * The `Reply` module models responses produced by clustered RPC execution. A
- * reply belongs to a request and is either a terminal {@link WithExit}, which
- * carries the final RPC `Exit`, or a streaming {@link Chunk}, which carries a
- * non-empty batch of success values for RPCs that stream results.
- *
- * **Common tasks**
- *
- * - Represent runtime replies with {@link Reply}, {@link WithExit}, and {@link Chunk}
- * - Encode and decode transport payloads with {@link Encoded} and {@link Reply}
- * - Persist replies together with schema context via {@link ReplyWithContext}
- * - Serialize the latest received reply when resuming or de-duplicating requests with {@link serializeLastReceived}
- *
- * **Streaming and acknowledgement notes**
- *
- * - Chunk replies are sequenced and can be replayed until acknowledged by the
- *   receiver.
- * - A `WithExit` reply is terminal and completes the request, while chunks only
- *   represent intermediate streamed success values.
- * - `Chunk.emptyFrom` is used as an acknowledgement marker for an empty streamed
- *   reply; it is not a general-purpose success payload.
- *
  * @since 4.0.0
  */
 export * as Reply from "./Reply.ts";
 /**
- * The `Runner` module defines the membership record used by the unstable
- * cluster runtime to describe a process 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.
- *
- * **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
- * - Tune shard distribution by adjusting the runner's group membership and
- *   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.
- *
  * @since 4.0.0
  */
 export * as Runner from "./Runner.ts";
 /**
- * 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.
- *
- * **Common use cases**
- *
- * - 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
- *
- * **Gotchas**
- *
- * - Identity is structural: two addresses are equal 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
- *
  * @since 4.0.0
  */
 export * as RunnerAddress from "./RunnerAddress.ts";
 /**
- * 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.
- *
- * **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
- *
- * **Gotchas**
- *
- * - Health checks affect shard reassignment, so false negatives can move shards
- *   away from runners that may still be processing messages
- * - The Kubernetes implementation treats API failures as healthy to avoid
- *   reassignment caused by a temporary control-plane outage
- *
  * @since 4.0.0
  */
 export * as RunnerHealth from "./RunnerHealth.ts";
 /**
- * The `Runners` module defines the service used by the unstable cluster runtime
- * to communicate with processes that host entity shards. It is the transport
- * boundary between sharding decisions and runner execution: callers can ping a
- * runner, send requests or envelopes, notify a runner that persisted work is
- * available, and report an address as unavailable.
- *
- * The default implementation wraps lower-level runner callbacks with cluster
- * message semantics. Persisted messages are written to `MessageStorage` before
- * delivery, duplicate requests can resume from stored replies, and local sends
- * can optionally serialize and deserialize messages to exercise the same path as
- * remote delivery.
- *
- * **Common tasks**
- *
- * - Provide runner communication with {@link layerRpc}
- * - Build a custom implementation with {@link make}
- * - Use {@link makeNoop} or {@link layerNoop} when no remote runners are
- *   available
- * - Define runner-to-runner protocol support with {@link Rpcs} and
- *   {@link RpcClientProtocol}
- *
- * **Gotchas**
- *
- * - `notify` is only for RPCs annotated as persisted; non-persisted messages
- *   should be sent directly.
- * - Failed remote sends can fall back to reading replies from storage, so reply
- *   polling and `entityReplyPollInterval` affect recovery latency.
- * - Unavailable runners invalidate cached RPC clients, but shard ownership and
- *   rebalancing are coordinated by the sharding layer rather than this module.
- *
  * @since 4.0.0
  */
 export * as Runners from "./Runners.ts";
 /**
- * The `RunnerServer` module provides the transport-agnostic server side of the
- * cluster runner protocol. It turns the runner RPC group into handlers that
- * receive ping, notification, request, stream, and envelope messages from other
- * runners, then forwards them into `Sharding` and coordinates persisted replies
- * through `MessageStorage`.
- *
- * **Common tasks**
- *
- * - Build a runner server once an `RpcServer.Protocol` has been supplied by a
- *   transport such as HTTP, WebSocket, or sockets
- * - Provide the complete runner runtime with `Sharding` and `Runners` clients
- *   using {@link layerWithClients}
- * - Embed a cluster client without serving runner RPCs or accepting shard
- *   assignments using {@link layerClientOnly}
- *
- * **Gotchas**
- *
- * - This module does not choose a wire transport; transport-specific modules
- *   provide the `RpcServer.Protocol`
- * - Persisted requests register reply handlers in `MessageStorage` before the
- *   message is delivered to `Sharding`
- * - Client-only layers clear the configured runner address, so they can send
- *   cluster messages but do not register as shard-owning runners
- *
  * @since 4.0.0
  */
 export * as RunnerServer from "./RunnerServer.ts";
 /**
- * The `RunnerStorage` module defines the persistence boundary used by clustered
- * runners to register themselves and coordinate shard ownership.
- *
- * Implementations keep track of runner metadata, health, machine ids, and shard
- * locks so a cluster can rebalance work as runners join, leave, or lose their
- * leases. Production adapters usually implement the string-encoded interface and
- * adapt it with {@link makeEncoded}; tests and local setups can use
- * {@link makeMemory}.
- *
- * **Common tasks**
- *
- * - Register and unregister runners in a shared store
- * - Read runner health for scheduling and rebalancing decisions
- * - Acquire, refresh, and release shard locks for distributed processing
- * - Bridge typed cluster values to string or numeric database representations
- *
- * **Gotchas**
- *
- * - Shard acquisition may be partial; callers must use the returned shard list
- * - Refreshing leases is part of keeping shard ownership during rebalancing
- * - The in-memory implementation is process-local and does not persist runner
- *   registrations or locks across restarts
- *
  * @since 4.0.0
  */
 export * as RunnerStorage from "./RunnerStorage.ts";
 /**
- * The `ShardId` module models the address of a shard inside an Effect Cluster
- * shard group. A shard id is made from a string `group` and numeric `id`, and
- * the module gives that pair stable equality, hashing, primary-key behavior,
- * schema support, and conversion to and from the `group:id` string form used by
- * routing and storage boundaries.
- *
- * **Common tasks**
- *
- * - Create or reuse a cached shard identifier with {@link make}
- * - Check runtime values with {@link isShardId}
- * - Encode or decode shard identifiers with {@link ShardId}
- * - Format for logs, persistence, or transport with {@link toString}
- * - Parse encoded shard keys with {@link fromString} or {@link fromStringEncoded}
- *
- * **Gotchas**
- *
- * - Equality and hashing are based on the `group:id` representation, so both
- *   fields must match for two shard ids to be equal
- * - Encoded strings are split at the last `:`; groups may contain colons, but
- *   ids must parse as numbers
- * - This module identifies shards after a routing or hashing decision; it does
- *   not choose a shard for an arbitrary entity key
- *
  * @since 4.0.0
  */
 export * as ShardId from "./ShardId.ts";
 /**
- * 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.
- *
- * 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.
- *
- * **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.
- *
  * @since 4.0.0
  */
 export * as Sharding from "./Sharding.ts";
 /**
- * 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.
- *
- * 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.
- *
  * @since 4.0.0
  */
 export * as ShardingConfig from "./ShardingConfig.ts";
 /**
- * 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.
- *
- * 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.
- *
  * @since 4.0.0
  */
 export * as ShardingRegistrationEvent from "./ShardingRegistrationEvent.ts";
 /**
- * The `SingleRunner` module provides a ready-to-use layer for running the
- * cluster sharding services in a single process. It wires together sharding,
- * message storage, runner registration, runner health, and sharding
- * configuration so durable entities and workflows can run without a fleet of
- * external runners.
- *
- * **Common tasks**
- *
- * - Start a local or embedded cluster runner backed by SQL message storage
- * - Run durable entities and workflows in development, tests, or small
- *   single-node deployments
- * - Choose SQL runner storage for persistence or in-memory runner storage for
- *   short-lived scenarios
- * - Override sharding configuration while still using the standard
- *   environment-based defaults
- *
- * **Gotchas**
- *
- * - The layer still requires a `SqlClient` because message storage is SQL-backed
- * - Runner health and runner coordination are no-op implementations, so this is
- *   for single-node use rather than multi-runner cluster coordination
- *
  * @since 4.0.0
  */
 export * as SingleRunner from "./SingleRunner.ts";
 /**
- * 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.
- *
- * 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.
- *
  * @since 4.0.0
  */
 export * as Singleton from "./Singleton.ts";
 /**
- * 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.
- *
  * @since 4.0.0
  */
 export * as SingletonAddress from "./SingletonAddress.ts";
 /**
- * The `Snowflake` module provides compact, sortable identifiers for cluster
- * resources and events. A snowflake id is a branded `bigint` made from a
- * millisecond timestamp, a machine id, and a per-machine sequence number.
- *
- * **Common use cases**
- *
- * - Creating ids without coordinating through a central database
- * - Ordering cluster events, entity ids, or log records by generation time
- * - Encoding ids as strings at service boundaries with {@link SnowflakeFromString}
- * - Decoding a generated id into timestamp, machine id, and sequence parts with {@link toParts}
- *
- * **Gotchas**
- *
- * - Uniqueness depends on each concurrent generator using a distinct machine id
- * - Generated ids are time-sortable, but they are not random or secret values
- * - The default generator prevents local clock drift from moving ids backward
- * - More than 4096 ids in the same millisecond advance the logical timestamp
- *
  * @since 4.0.0
  */
 export * as Snowflake from "./Snowflake.ts";
 /**
- * The `SocketRunner` module wires cluster runner RPCs to socket transports. It
- * provides a complete runner layer that serves RPC handlers on a `SocketServer`
- * and installs `Sharding` and `Runners` clients for talking to other runners
- * through the socket RPC protocol.
- *
- * **Common tasks**
- *
- * - Run a cluster worker over TCP or Unix sockets with {@link layer}
- * - Connect to other runners while exposing `Sharding` and `Runners` clients
- * - Embed a client-only cluster participant with {@link layerClientOnly} when
- *   the process should send messages but not receive shard assignments
- *
- * **Transport gotchas**
- *
- * - The server listen address comes from the provided `SocketServer` and is
- *   logged when {@link layer} starts
- * - TCP addresses are logged as `hostname:port`, while Unix socket addresses
- *   are logged as their filesystem path
- * - The client-only layer does not start a socket server; provide the full
- *   layer when the process must accept runner RPCs
- *
  * @since 4.0.0
  */
 export * as SocketRunner from "./SocketRunner.ts";
 /**
- * SQL-backed message storage for the unstable cluster runtime.
- *
- * This module persists encoded cluster envelopes and replies in SQL tables so
- * shards can resume work after process restarts, redeliver unprocessed messages,
- * deduplicate requests by primary key, and replay outstanding reply chunks until
- * they are acknowledged. It is the storage implementation to use when a cluster
- * needs durable request / reply state backed by `SqlClient` rather than an
- * in-memory store.
- *
- * The storage layer runs its own migrations and creates messages, replies, and
- * migration tables using the configured prefix (`cluster` by default). Choose a
- * stable prefix before deploying, because changing it points the runtime at a
- * different set of tables. Existing deployments should also keep the generated
- * migration history table with the message tables so future schema changes can
- * be applied consistently across supported SQL dialects.
- *
  * @since 4.0.0
  */
 export * as SqlMessageStorage from "./SqlMessageStorage.ts";
 /**
- * SQL-backed storage for Effect Cluster runner metadata and shard ownership.
- *
- * The `SqlRunnerStorage` module builds a `RunnerStorage` implementation from a
- * `SqlClient`, creating the runner and lock tables it needs using the configured
- * table prefix. It is used by clustered applications that need runner
- * registration, health tracking, shard acquisition, refresh, and release to be
- * coordinated through an external database instead of in-memory state.
- *
- * **Common tasks**
- *
- * - Provide the default storage layer with {@link layer}
- * - Use {@link layerWith} when multiple clusters share the same database and
- *   need distinct table prefixes
- * - Create a storage implementation directly with {@link make} for custom layer
- *   composition
- *
- * **Gotchas**
- *
- * - Runner heartbeats and persisted shard locks expire according to
- *   `ShardingConfig.shardLockExpiration`; stale rows may be reused or cleaned up
- *   by later storage operations.
- * - PostgreSQL and MySQL use advisory locks by default, keeping shard ownership
- *   tied to a reserved database connection. Set
- *   `ShardingConfig.shardLockDisableAdvisory` when persisted lock rows should be
- *   used instead.
- * - The selected table prefix controls the generated `runners` and `locks`
- *   table names, so changing it points the cluster at a different storage
- *   namespace.
- *
  * @since 4.0.0
  */
 export * as SqlRunnerStorage from "./SqlRunnerStorage.ts";
 /**
- * The `TestRunner` module provides a lightweight in-memory cluster layer for
- * tests that need the cluster sharding services without starting real runners
- * or relying on external storage.
- *
- * Use it when exercising sharding behavior, message storage, or code that
- * depends on the cluster runner services in unit and integration tests. The
- * layer wires the normal sharding service to in-memory message and runner
- * storage, along with no-op runner and health implementations.
- *
- * **Testing gotchas**
- *
- * - State is held in memory and scoped to the layer lifetime; it is not shared
- *   across independently constructed layers or persisted between test runs
- * - Runner execution and health checks are no-ops, so this layer is best suited
- *   for testing coordination and storage behavior rather than real distributed
- *   runner processes
- *
  * @since 4.0.0
  */
 export * as TestRunner from "./TestRunner.ts";