effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/cluster/RunnerStorage.ts

@@ -1,4 +1,27 @@
 /**
+ * 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
  */
 import { isArrayNonEmpty, type NonEmptyArray } from "../../Array.ts"
@@ -16,8 +39,8 @@ import * as ShardId from "./ShardId.ts"
  * Represents a generic interface to the persistent storage required by the
  * cluster.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class RunnerStorage extends Context.Service<RunnerStorage, {
   /**
@@ -73,8 +96,11 @@ export class RunnerStorage extends Context.Service<RunnerStorage, {
 }>()("effect/cluster/RunnerStorage") {}
 
 /**
- * @since 4.0.0
+ * String-encoded runner storage interface used by adapters that persist runner
+ * addresses, runners, machine ids, and shard ids outside the in-memory model.
+ *
  * @category Encoded
+ * @since 4.0.0
  */
 export interface Encoded {
   /**
@@ -130,8 +156,12 @@ export interface Encoded {
 }
 
 /**
- * @since 4.0.0
+ * Adapts an encoded runner storage implementation into `RunnerStorage`, converting
+ * runner addresses, runners, machine ids, and shard ids between typed values and
+ * their string or numeric storage forms.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const makeEncoded = (encoded: Encoded) =>
   RunnerStorage.of({
@@ -176,8 +206,13 @@ export const makeEncoded = (encoded: Encoded) =>
   })
 
 /**
- * @since 4.0.0
+ * Creates an in-memory `RunnerStorage` implementation for tests and local use.
+ *
+ * Registered runners are treated as healthy and shard acquisition is kept only in
+ * process memory.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeMemory = Effect.gen(function*() {
   const runners = MutableHashMap.empty<RunnerAddress, Runner>()
@@ -207,8 +242,10 @@ export const makeMemory = Effect.gen(function*() {
 })
 
 /**
- * @since 4.0.0
+ * Layer that provides the in-memory `RunnerStorage` implementation.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerMemory: Layer.Layer<RunnerStorage> = Layer.effect(RunnerStorage)(makeMemory)
 

package/src/unstable/cluster/Runners.ts

@@ -1,4 +1,34 @@
 /**
+ * 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
  */
 import * as Context from "../../Context.ts"
@@ -28,8 +58,12 @@ import { ShardingConfig } from "./ShardingConfig.ts"
 import * as Snowflake from "./Snowflake.ts"
 
 /**
- * @since 1.0.0
+ * Service for communicating with cluster runners, including pinging runners,
+ * sending and notifying messages, coordinating persisted replies, and marking
+ * runners unavailable.
+ *
  * @category context
+ * @since 4.0.0
  */
 export class Runners extends Context.Service<Runners, {
   /**
@@ -112,8 +146,12 @@ export class Runners extends Context.Service<Runners, {
 }>()("effect/cluster/Runners") {}
 
 /**
- * @since 1.0.0
+ * Builds the `Runners` service from remote runner callbacks and adds local
+ * message persistence, duplicate request handling, optional local serialization
+ * simulation, and polling for persisted replies.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make: (options: Omit<Runners["Service"], "sendLocal" | "notifyLocal">) => Effect.Effect<
   Runners["Service"],
@@ -380,8 +418,12 @@ export const make: (options: Omit<Runners["Service"], "sendLocal" | "notifyLocal
 })
 
 /**
- * @since 1.0.0
+ * Creates a no-op `Runners` service that rejects sends with
+ * `EntityNotAssignedToRunner` and ignores notifications, pings, and unavailable
+ * runner reports.
+ *
  * @category No-op
+ * @since 4.0.0
  */
 export const makeNoop: Effect.Effect<
   Runners["Service"],
@@ -395,8 +437,11 @@ export const makeNoop: Effect.Effect<
 })
 
 /**
- * @since 1.0.0
+ * Layer that provides the no-op `Runners` service, using the default snowflake
+ * generator.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerNoop: Layer.Layer<
   Runners,
@@ -415,8 +460,11 @@ const rpcErrors: Schema.Union<[
 ])
 
 /**
- * @since 1.0.0
+ * RPC group used for runner-to-runner communication, including ping, notify,
+ * effect, stream, and envelope messages.
+ *
  * @category Rpcs
+ * @since 4.0.0
  */
 export class Rpcs extends RpcGroup.make(
   Rpc.make("Ping"),
@@ -454,14 +502,19 @@ export class Rpcs extends RpcGroup.make(
 ) {}
 
 /**
- * @since 1.0.0
+ * Client interface generated from the runner RPC group.
+ *
  * @category Rpcs
+ * @since 4.0.0
  */
 export interface RpcClient extends RpcClient_.FromGroup<typeof Rpcs, RpcClientError> {}
 
 /**
- * @since 1.0.0
+ * Builds a runner RPC client from the current `RpcClient.Protocol`, using the
+ * `Runners` span prefix with tracing disabled.
+ *
  * @category Rpcs
+ * @since 4.0.0
  */
 export const makeRpcClient: Effect.Effect<
   RpcClient,
@@ -470,8 +523,12 @@ export const makeRpcClient: Effect.Effect<
 > = RpcClient_.make(Rpcs, { spanPrefix: "Runners", disableTracing: true })
 
 /**
- * @since 1.0.0
+ * Builds a `Runners` service backed by RPC clients, caching a client per runner
+ * address and dispatching ping, notify, effect, stream, and envelope messages over
+ * the runner protocol.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeRpc: Effect.Effect<
   Runners["Service"],
@@ -603,8 +660,11 @@ export const makeRpc: Effect.Effect<
 })
 
 /**
- * @since 1.0.0
+ * Layer that provides an RPC-backed `Runners` service using `RpcClientProtocol`,
+ * message storage, sharding configuration, and the default snowflake generator.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerRpc: Layer.Layer<
   Runners,
@@ -615,8 +675,11 @@ export const layerRpc: Layer.Layer<
 )
 
 /**
- * @since 1.0.0
+ * Service that creates an RPC client protocol for communicating with a runner at a
+ * given address.
+ *
  * @category Client
+ * @since 4.0.0
  */
 export class RpcClientProtocol extends Context.Service<
   RpcClientProtocol,

package/src/unstable/cluster/ShardId.ts

@@ -1,4 +1,27 @@
 /**
+ * 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
  */
 import * as Equal from "../../Equal.ts"
@@ -11,8 +34,11 @@ import * as Getter from "../../SchemaGetter.ts"
 const TypeId = "~effect/cluster/ShardId"
 
 /**
- * @since 4.0.0
+ * Identifier for a shard within a shard group, with equality, hashing, and primary
+ * key behavior based on the `group:id` string form.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface ShardId extends Equal.Equal, Hash.Hash, PrimaryKey.PrimaryKey {
   readonly [TypeId]: typeof TypeId
@@ -21,14 +47,19 @@ export interface ShardId extends Equal.Equal, Hash.Hash, PrimaryKey.PrimaryKey {
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` when the value carries the `ShardId` runtime marker.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export const isShardId = (u: unknown): u is ShardId => hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Schema for `ShardId` values encoded as `{ group, id }` objects and decoded via
+ * `make`.
+ *
  * @category Schema
+ * @since 4.0.0
  */
 export const ShardId = S.declare(isShardId, {
   toCodecJson: () =>
@@ -45,8 +76,11 @@ export const ShardId = S.declare(isShardId, {
 })
 
 /**
- * @since 4.0.0
+ * Creates or reuses the cached `ShardId` for the specified shard group and numeric
+ * id.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = (group: string, id: number): ShardId => {
   const key = `${group}:${id}`
@@ -84,8 +118,10 @@ const ShardIdProto = {
 }
 
 /**
- * @since 4.0.0
+ * Formats a shard identifier as `group:id`.
+ *
  * @category Conversions
+ * @since 4.0.0
  */
 export const toString = (shardId: {
   readonly group: string
@@ -94,6 +130,11 @@ export const toString = (shardId: {
   return `${shardId.group}:${shardId.id}`
 }
 /**
+ * Parses a `group:id` string into plain shard id parts.
+ *
+ * Throws an `Error` when the string has no colon separator or the id segment is
+ * not numeric.
+ *
  * @since 4.0.0
  */
 export function fromStringEncoded(s: string): {
@@ -113,6 +154,11 @@ export function fromStringEncoded(s: string): {
 }
 
 /**
+ * Parses a `group:id` string into a cached `ShardId`.
+ *
+ * Throws an `Error` when the string has no colon separator or the id segment is
+ * not numeric.
+ *
  * @since 4.0.0
  */
 export function fromString(s: string): ShardId {

package/src/unstable/cluster/Sharding.ts

@@ -1,4 +1,26 @@
 /**
+ * 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 {@link Sharding.makeClient} 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
  */
 import * as Arr from "../../Array.ts"
@@ -56,14 +78,18 @@ import { Runners } from "./Runners.ts"
 import { RunnerStorage } from "./RunnerStorage.ts"
 import type { ShardId } from "./ShardId.ts"
 import { make as makeShardId } from "./ShardId.ts"
-import { ShardingConfig } from "./ShardingConfig.ts"
+import { shardGroupConfig, ShardingConfig } from "./ShardingConfig.ts"
 import { EntityRegistered, type ShardingRegistrationEvent, SingletonRegistered } from "./ShardingRegistrationEvent.ts"
 import { SingletonAddress } from "./SingletonAddress.ts"
 import * as Snowflake from "./Snowflake.ts"
 
 /**
- * @since 4.0.0
+ * Cluster sharding service for registering entities and singletons, routing
+ * messages to owned shards, generating runner-local snowflake ids, and polling
+ * storage for persisted work.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class Sharding extends Context.Service<Sharding, {
   /**
@@ -199,6 +225,7 @@ interface EntityManagerState {
 
 const make = Effect.gen(function*() {
   const config = yield* ShardingConfig
+  const shardGroups = shardGroupConfig(config)
   const getRunnerAddress = () => Option.getOrUndefined(config.runnerAddress)
   const clock = yield* Clock
 
@@ -871,7 +898,7 @@ const make = Effect.gen(function*() {
   const selfRunner = initialRunnerAddress ?
     new Runner({
       address: initialRunnerAddress,
-      groups: config.shardGroups,
+      groups: Array.from(shardGroups.assigned),
       weight: config.runnerShardWeight
     }) :
     undefined
@@ -1430,8 +1457,12 @@ const make = Effect.gen(function*() {
 })
 
 /**
- * @since 4.0.0
+ * Layer that constructs the `Sharding` service from sharding configuration,
+ * runner communication, message storage, runner storage, runner health, the
+ * snowflake generator, and the entity reaper.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<
   Sharding,

package/src/unstable/cluster/ShardingConfig.ts

@@ -1,4 +1,19 @@
 /**
+ * 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
  */
 import * as Config from "../../Config.ts"
@@ -14,8 +29,8 @@ import { RunnerAddress } from "./RunnerAddress.ts"
 /**
  * Represents the configuration for the `Sharding` service on a given runner.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class ShardingConfig extends Context.Service<ShardingConfig, {
   /**
@@ -42,12 +57,18 @@ export class ShardingConfig extends Context.Service<ShardingConfig, {
    * shards as a runner with a weight of `1`.
    */
   readonly runnerShardWeight: number
+  /**
+   * The shard groups available across all runners.
+   *
+   * Defaults to `["default"]`.
+   */
+  readonly availableShardGroups: ReadonlyArray<string>
   /**
    * The shard groups that are assigned to this runner.
    *
    * Defaults to `["default"]`.
    */
-  readonly shardGroups: ReadonlyArray<string>
+  readonly assignedShardGroups: ReadonlyArray<string>
   /**
    * The number of shards to allocate per shard group.
    *
@@ -125,15 +146,20 @@ export class ShardingConfig extends Context.Service<ShardingConfig, {
 const defaultRunnerAddress = RunnerAddress.make({ host: "localhost", port: 34431 })
 
 /**
- * @since 4.0.0
+ * Default values for `ShardingConfig`, including the default local runner address,
+ * shard group, shard count, mailbox settings, polling intervals, and remote
+ * serialization simulation.
+ *
  * @category defaults
+ * @since 4.0.0
  */
 export const defaults: ShardingConfig["Service"] = {
   runnerAddress: Option.some(defaultRunnerAddress),
   runnerListenAddress: Option.none(),
   runnerShardWeight: 1,
   shardsPerGroup: 300,
-  shardGroups: ["default"],
+  availableShardGroups: ["default"],
+  assignedShardGroups: ["default"],
   preemptiveShutdown: true,
   shardLockRefreshInterval: Duration.seconds(10),
   shardLockExpiration: Duration.seconds(35),
@@ -151,21 +177,29 @@ export const defaults: ShardingConfig["Service"] = {
 }
 
 /**
- * @since 4.0.0
+ * Creates a `ShardingConfig` layer by merging the provided partial options over
+ * `defaults`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer = (options?: Partial<ShardingConfig["Service"]>): Layer.Layer<ShardingConfig> =>
   Layer.succeed(ShardingConfig)({ ...defaults, ...options })
 
 /**
- * @since 4.0.0
+ * Layer that provides the default `ShardingConfig` values.
+ *
  * @category defaults
+ * @since 4.0.0
  */
 export const layerDefaults: Layer.Layer<ShardingConfig> = layer()
 
 /**
- * @since 4.0.0
+ * Config descriptor for loading `ShardingConfig` values, applying the same
+ * defaults used by the in-memory `defaults` object.
+ *
  * @category Config
+ * @since 4.0.0
  */
 export const config: Config.Config<ShardingConfig["Service"]> = Config.all({
   runnerAddress: Config.all({
@@ -190,7 +224,11 @@ export const config: Config.Config<ShardingConfig["Service"]> = Config.all({
     Config.withDefault(defaults.runnerShardWeight)
     // Config.withDescription("A number that determines how many shards this runner will be assigned relative to other runners.")
   ),
-  shardGroups: Config.schema(Schema.Array(Schema.String), "shardGroups").pipe(
+  availableShardGroups: Config.schema(Schema.Array(Schema.String), "availableShardGroups").pipe(
+    Config.withDefault(["default"])
+    // Config.withDescription("The shard groups available across all runners.")
+  ),
+  assignedShardGroups: Config.schema(Schema.Array(Schema.String), "shardGroups").pipe(
     Config.withDefault(["default"])
     // Config.withDescription("The shard groups that are assigned to this runner.")
   ),
@@ -260,10 +298,13 @@ export const config: Config.Config<ShardingConfig["Service"]> = Config.all({
 })
 
 /**
- * @since 4.0.0
+ * Effect that loads `ShardingConfig` from environment variables using the
+ * constant-case config provider.
+ *
  * @category Config
+ * @since 4.0.0
  */
-export const configFromEnv = config.asEffect().pipe(
+export const configFromEnv = config.pipe(
   Effect.provideService(
     ConfigProvider.ConfigProvider,
     ConfigProvider.fromEnv().pipe(
@@ -273,8 +314,11 @@ export const configFromEnv = config.asEffect().pipe(
 )
 
 /**
- * @since 4.0.0
+ * Layer that loads `ShardingConfig` from environment variables and, when options
+ * are provided, overlays those options on top of the loaded values.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerFromEnv = (options?: Partial<ShardingConfig["Service"]> | undefined): Layer.Layer<
   ShardingConfig,
@@ -283,3 +327,24 @@ export const layerFromEnv = (options?: Partial<ShardingConfig["Service"]> | unde
   Layer.effect(ShardingConfig)(
     options ? Effect.map(configFromEnv, (config) => ({ ...config, ...options })) : configFromEnv
   )
+
+/**
+ * Normalizes the provided `ShardingConfig` to calculate the `available` and
+ * `assigned` shard groups.
+ *
+ * @category Shard groups
+ * @since 4.0.0
+ */
+export const shardGroupConfig = (config: ShardingConfig["Service"]): {
+  readonly available: ReadonlySet<string>
+  readonly assigned: ReadonlySet<string>
+} => {
+  const available = new Set(config.availableShardGroups.slice().sort())
+  const assigned = new Set<string>()
+  available.forEach((group) => {
+    if (config.assignedShardGroups.includes(group)) {
+      assigned.add(group)
+    }
+  })
+  return { available, assigned }
+}

package/src/unstable/cluster/ShardingRegistrationEvent.ts

@@ -1,4 +1,18 @@
 /**
+ * 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
  */
 import * as Data from "../../Data.ts"
@@ -8,8 +22,8 @@ import type { SingletonAddress } from "./SingletonAddress.ts"
 /**
  * Represents events that can occur when a runner registers entities or singletons.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type ShardingRegistrationEvent =
   | EntityRegistered
@@ -18,8 +32,8 @@ export type ShardingRegistrationEvent =
 /**
  * Represents an event that occurs when a new entity is registered with a runner.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface EntityRegistered {
   readonly _tag: "EntityRegistered"
@@ -30,8 +44,8 @@ export interface EntityRegistered {
  * Represents an event that occurs when a new singleton is registered with a
  * runner.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface SingletonRegistered {
   readonly _tag: "SingletonRegistered"
@@ -39,23 +53,33 @@ export interface SingletonRegistered {
 }
 
 /**
- * @since 4.0.0
+ * Generated helpers for pattern matching and constructing sharding registration
+ * events.
+ *
  * @category pattern matching
+ * @since 4.0.0
  */
 export const {
   /**
-   * @since 4.0.0
+   * Pattern matches on a sharding registration event and dispatches to the
+   * matching variant handler.
+   *
    * @category pattern matching
+   * @since 4.0.0
    */
   $match: match,
   /**
-   * @since 4.0.0
+   * Creates an event for an entity registered by the local runner.
+   *
    * @category constructors
+   * @since 4.0.0
    */
   EntityRegistered,
   /**
-   * @since 4.0.0
+   * Creates an event for a singleton registered by the local runner.
+   *
    * @category constructors
+   * @since 4.0.0
    */
   SingletonRegistered
 } = Data.taggedEnum<ShardingRegistrationEvent>()