effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/unstable/cluster/EntityId.ts

@@ -4,30 +4,6 @@
  * hashes, stores in entity addresses, and uses when sending messages to a
  * running entity.
  *
- * **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
  */
 import * as Schema from "../../Schema.ts"

package/src/unstable/cluster/EntityProxy.ts

@@ -1,25 +1,11 @@
 /**
- * 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`.
+ * Derives RPC and HTTP API surfaces from clustered entities.
  *
- * **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.
+ * The generated APIs let callers use ordinary RPC clients or HTTP routes while
+ * the cluster runtime still locates and delivers messages to the entity
+ * instance identified by `entityId`. Each generated operation keeps the
+ * original payload and success schema, adds cluster client errors, and creates
+ * a discard variant for fire-and-forget delivery.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/EntityProxyServer.ts

@@ -1,24 +1,12 @@
 /**
- * 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.
+ * Serves the proxy APIs generated from clustered entities.
  *
- * **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
+ * Proxy handlers read the target `entityId`, call the entity client, and
+ * forward the payload to the matching entity RPC method. This module provides
+ * handlers for HTTP API groups created by `EntityProxy.toHttpApiGroup` and RPC
+ * handler services for RPC groups created by `EntityProxy.toRpcGroup`. Both
+ * normal requests and discard requests are forwarded to the underlying entity
+ * client.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/EntityResource.ts

@@ -1,26 +1,12 @@
 /**
- * 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
+ * Keeps resources available across cluster entity restarts.
+ *
+ * `EntityResource` is useful for long-lived resources tied to an entity
+ * address, such as external processes, network clients, Kubernetes Pods, or
+ * other handles that should survive routine shard movement. This module
+ * includes the resource wrapper, a close scope that survives normal entity
+ * restarts, a generic resource constructor, and a Kubernetes Pod resource
+ * helper built on `K8sHttpClient`.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/EntityType.ts

@@ -4,19 +4,6 @@
  * 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
  */
 import * as Schema from "../../Schema.ts"

package/src/unstable/cluster/Envelope.ts

@@ -1,26 +1,11 @@
 /**
- * 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.
+ * Defines the transport envelopes exchanged by cluster entities.
+ *
+ * Request envelopes wrap decoded RPC payloads with the target entity address,
+ * RPC tag, request id, headers, and optional tracing context. The module also
+ * includes acknowledgement envelopes for streamed reply chunks, interrupt
+ * envelopes for in-flight requests, JSON codecs for partially decoded
+ * envelopes, guards, request constructors, and storage primary-key helpers.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/HttpRunner.ts

@@ -1,38 +1,11 @@
 /**
- * HTTP and WebSocket transport layers for cluster runner RPCs.
+ * Connects cluster runner RPCs to HTTP and WebSocket transports.
  *
  * 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 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}
- * - Build custom client protocols with {@link layerClientProtocolHttp} or
- *   {@link layerClientProtocolWebsocket}
- *
- * **Gotchas**
- *
- * - 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 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`
+ * provides client protocol layers for dialing runner addresses over HTTP or
+ * WebSocket, HTTP effects that serve runner RPC handlers, route layers for
+ * installing runner endpoints into an `HttpRouter`, and ready-made layers for
+ * HTTP or WebSocket runner communication.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/K8sHttpClient.ts

@@ -4,38 +4,6 @@
  * shared HTTP client, points requests at the in-cluster API endpoint, and uses
  * the mounted service-account token when one is available.
  *
- * **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 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
  */
 import type * as v1 from "kubernetes-types/core/v1.d.ts"

package/src/unstable/cluster/MachineId.ts

@@ -4,26 +4,6 @@
  * generation, while keeping the value distinct from an ordinary `number` in
  * TypeScript APIs.
  *
- * **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**
- *
- * - 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**
- *
- * - 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
  */
 import * as Schema from "../../Schema.ts"

package/src/unstable/cluster/Message.ts

@@ -1,27 +1,11 @@
 /**
- * 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.
+ * Defines the message shapes moved through Effect Cluster.
+ *
+ * Messages carry entity requests and control envelopes between callers, durable
+ * storage, transports, and runner handlers. This module includes incoming and
+ * outgoing variants for encoded stored requests, decoded local requests,
+ * acknowledgements, and interrupts. It also provides helpers for local delivery
+ * and for encoding or decoding request payloads with matching RPC schemas.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/MessageStorage.ts

@@ -1,41 +1,12 @@
 /**
- * Persistence and reply delivery for Effect Cluster mailboxes.
+ * Stores Effect Cluster messages and replies behind a pluggable backend.
  *
- * `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.
- *
- * **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**
- *
- * - 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.
- * - 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.
+ * `MessageStorage` is the boundary between cluster runner logic and the storage
+ * system that keeps mailbox state recoverable. It saves requests, control
+ * envelopes, and replies; finds unprocessed messages for assigned shards;
+ * tracks duplicate requests; and manages reply handlers waiting for responses.
+ * This module also includes the encoded storage-driver contract and no-op or
+ * in-memory implementations for local use and tests.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/Reply.ts

@@ -1,24 +1,12 @@
 /**
- * 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.
+ * Defines reply values produced by clustered RPC execution.
  *
- * **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.
+ * Every reply belongs to a request and is either a final `WithExit`, which
+ * carries the final RPC `Exit`, or a streaming `Chunk`, which carries a
+ * non-empty batch of success values. This module includes runtime and encoded
+ * reply shapes, guards, per-RPC schema builders, `ReplyWithContext` for
+ * carrying encoding services, and serialization helpers for storage or
+ * transport.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/Runner.ts

@@ -1,41 +1,9 @@
 /**
  * Cluster runner metadata for processes that can host entity shards.
  *
- * 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 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.
- *
- * **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 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}
+ * A `Runner` combines the stable `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.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/RunnerAddress.ts

@@ -1,36 +1,8 @@
 /**
- * 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.
- *
- * **Mental model**
- *
- * `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 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.
- * - The constructor does not check whether the endpoint is reachable.
- *
- * **See also**
- *
- * - {@link RunnerAddress}
- * - {@link make}
+ * Network addresses for locating cluster runners. A `RunnerAddress` stores the
+ * host and port for a runner and provides schema support, structural equality,
+ * hashing, Node.js inspection, and a stable primary key formatted from the host
+ * and port.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/RunnerHealth.ts

@@ -1,40 +1,11 @@
 /**
- * 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.
+ * Checks whether cluster runners should be treated as alive.
  *
- * **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 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**
- *
- * - 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.
- * - {@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}
+ * `RunnerHealth` is used by sharding when deciding whether assigned shards can
+ * stay on a runner or need to move elsewhere. This module includes the
+ * health-check service, a no-op layer that always reports runners as alive, a
+ * ping-based checker, and a Kubernetes-based checker that looks at pod readiness
+ * for the runner host.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/RunnerServer.ts

@@ -1,27 +1,12 @@
 /**
- * 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
+ * Provides server-side layers for the cluster runner protocol.
+ *
+ * Runner protocol handlers receive ping, notification, request, stream, and
+ * envelope messages from other runners. They forward those messages into
+ * `Sharding` and coordinate persisted replies through `MessageStorage`. This
+ * module includes the handler layer, a transport-independent RPC server layer, a
+ * full server layer that also provides runner clients, and a client-only layer
+ * for applications that do not serve runner RPCs.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/RunnerStorage.ts

@@ -1,26 +1,11 @@
 /**
- * The `RunnerStorage` module defines the persistence boundary used by clustered
- * runners to register themselves and coordinate shard ownership.
+ * Stores runner registration and shard-lock state for cluster sharding.
  *
- * 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
+ * `RunnerStorage` records which runners are registered, whether they are
+ * healthy, which machine id a runner receives, and which shard locks are held
+ * by each runner. This module includes the typed storage service, a
+ * string-encoded backend interface, an adapter from encoded storage to the typed
+ * service, and an in-memory implementation for tests and local use.
  *
  * @since 4.0.0
  */