effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/cli/index.ts

@@ -5,21 +5,116 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * The `Argument` module defines typed positional command-line arguments for
+ * Effect CLI applications. Arguments consume ordered values after a command name
+ * and its flags, then parse them into the types your command handler expects.
+ *
+ * Use this module for required inputs such as file paths, directories, numbers,
+ * dates, choices, secrets, and structured configuration files. Arguments can be
+ * made optional, variadic, validated with Schema, transformed with pure or
+ * effectful functions, and supplied from defaults, config, or prompts when
+ * missing.
+ *
+ * **Gotchas**
+ *
+ * - Positional arguments are order-sensitive; compose them in the same order the
+ *   user should type them.
+ * - `variadic` arguments can consume more than one value, so place them where
+ *   the remaining positional input belongs.
+ * - Use {@link withDescription} and {@link withMetavar} to keep generated help
+ *   text clear, especially when the parser name differs from the value users
+ *   should provide.
+ * - Boolean positional arguments are intentionally not provided. Prefer boolean
+ *   flags, or use {@link choice} for explicit `"true"` / `"false"` values.
+ *
  * @since 4.0.0
  */
 export * as Argument from "./Argument.ts"
 
 /**
+ * The `CliError` module defines the structured error model used by the
+ * unstable CLI parser and runner. It distinguishes command-line parse failures,
+ * CLI definition problems, explicit help requests, and user handler failures so
+ * applications can report errors consistently while still pattern matching on
+ * the exact cause.
+ *
+ * **Common tasks**
+ *
+ * - Detect CLI errors at runtime with {@link isCliError}
+ * - Represent parse failures such as unknown flags, missing required inputs, or
+ *   invalid argument values
+ * - Attach parse or validation errors to {@link ShowHelp} when the runner should
+ *   render help text together with the failure
+ * - Preserve command handler failures with {@link UserError}
+ *
+ * **Gotchas**
+ *
+ * - {@link ShowHelp} is a control-flow error, not a parse failure; it exits with
+ *   code `0` for explicit help and `1` when it carries errors
+ * - Duplicate option names between parent and child commands are rejected
+ *   because the parent command claims the flag before the child can see it
+ * - Suggestion-bearing errors keep suggestions separate from the primary cause
+ *   so help renderers can decide how much guidance to display
+ *
  * @since 4.0.0
  */
 export * as CliError from "./CliError.ts"
 
 /**
+ * The `CliOutput` module provides the formatting service used by Effect CLI
+ * applications to turn parsed CLI metadata and failures into terminal text.
+ * It renders help documents, parser errors, grouped errors, and version output,
+ * while allowing applications and tests to replace the formatter through a
+ * `Context` service or `Layer`.
+ *
+ * **Common tasks**
+ *
+ * - Render generated {@link HelpDoc} values for `--help` output
+ * - Display parser failures and validation errors from CLI programs
+ * - Customize output for plain text, colored terminals, tests, or alternate
+ *   formats
+ * - Format version strings consistently with the rest of CLI output
+ *
+ * **Gotchas**
+ *
+ * - Color output is auto-detected from `process.stdout.isTTY` and `NO_COLOR`,
+ *   but can be forced with {@link defaultFormatter}
+ * - Help tables measure visible width after stripping ANSI escape codes, so
+ *   colored output stays aligned with plain output
+ *
  * @since 4.0.0
  */
 export * as CliOutput from "./CliOutput.ts"
 
 /**
+ * The `Command` module provides the core building block for defining and
+ * running Effect-based command-line applications. A `Command` combines a name,
+ * typed flags and positional arguments, optional subcommands, metadata for help
+ * output, and an effectful handler.
+ *
+ * **Common tasks**
+ *
+ * - Create commands with {@link make}
+ * - Add handlers with {@link withHandler}
+ * - Build nested command trees with {@link withSubcommands}
+ * - Share parent flags with subcommands using {@link withSharedFlags}
+ * - Add command-scoped global flags with {@link withGlobalFlags}
+ * - Attach help metadata with {@link withDescription}, {@link withShortDescription},
+ *   {@link withAlias}, and {@link withExamples}
+ * - Provide handler dependencies with {@link provide}, {@link provideSync},
+ *   {@link provideEffect}, and {@link provideEffectDiscard}
+ * - Execute commands with {@link run} or test them with {@link runWith}
+ *
+ * **Gotchas**
+ *
+ * - `withSharedFlags` accepts only flags, not positional arguments, and the
+ *   parsed values are available to descendants by yielding the parent command.
+ * - Shared flags may be written before or after the selected subcommand name.
+ * - Duplicate flags across command scopes are rejected so parsing and help
+ *   output remain unambiguous.
+ * - `runWith` is the preferred entry point for tests because it accepts an
+ *   explicit argument array instead of reading from the `Stdio` service.
+ *
  * @since 4.0.0
  */
 export * as Command from "./Command.ts"
@@ -32,30 +127,110 @@ export * as Command from "./Command.ts"
 export * as Completions from "./Completions.ts"
 
 /**
+ * The `Flag` module provides typed command-line options for Effect CLI
+ * applications. A `Flag<A>` describes how to read one named option from the
+ * parsed command line, validate it, and produce a value of type `A`.
+ *
+ * Use flags for inputs that are naturally named options, such as ports,
+ * verbosity switches, configuration files, output directories, enum-like
+ * choices, secrets, and repeated values. Constructors such as {@link string},
+ * {@link boolean}, {@link integer}, {@link file}, and {@link fileSchema}
+ * define the accepted input shape, while combinators add aliases, defaults,
+ * optionality, fallback config or prompts, validation, and typed mapping.
+ *
+ * Flag names are rendered as long options, for example `Flag.integer("port")`
+ * parses `--port 8080`. Boolean flags also support the disabled form shown by
+ * this module's boolean documentation, and repeated flags are modeled with the
+ * repetition combinators instead of by manually inspecting raw arguments. Help
+ * text is generated from flag metadata, so prefer {@link withDescription} and
+ * {@link withMetavar} when a flag's value, format, or file-system expectation
+ * would otherwise be ambiguous.
+ *
  * @since 4.0.0
  */
 export * as Flag from "./Flag.ts"
 
 /**
+ * The `GlobalFlag` module defines flags that are available to every command in
+ * an Effect CLI application. Global flags are useful for cross-cutting command
+ * line behavior such as printing help, showing the application version,
+ * generating shell completions, or configuring shared handler settings like the
+ * minimum log level.
+ *
+ * **Common tasks**
+ *
+ * - Create an action flag with {@link action} for side effects that should run
+ *   before the selected command, such as `--help` or `--version`
+ * - Create a setting flag with {@link setting} for values that should be made
+ *   available to command handlers through the Effect context
+ * - Reuse the built-in {@link Help}, {@link Version}, {@link Completions}, and
+ *   {@link LogLevel} flags when constructing command runners
+ *
+ * **Gotchas**
+ *
+ * - Action flags are intended to perform their effect and exit instead of
+ *   continuing into the command handler
+ * - Setting flags allocate a distinct context service for each call to
+ *   {@link setting}, so reuse exported settings when handlers need to read the
+ *   same parsed global value
+ *
  * @since 4.0.0
  */
 export * as GlobalFlag from "./GlobalFlag.ts"
 
 /**
+ * The `HelpDoc` module defines the structured documentation model used by the
+ * unstable CLI package to describe command help. A `HelpDoc` value captures the
+ * user-facing parts of a command, including its description, usage string,
+ * positional arguments, flags, global flags, subcommands, and examples.
+ *
+ * **Common tasks**
+ *
+ * - Build help data from command definitions before rendering it
+ * - Pass command documentation to `CliOutput.Formatter` implementations
+ * - Represent custom help output formats without changing command parsing
+ * - Group subcommands and distinguish local flags from global flags
+ *
+ * **Gotchas**
+ *
+ * - `HelpDoc` is format-agnostic; layout, ANSI styling, and table alignment are
+ *   handled by the output formatter
+ * - Optional argument and flag descriptions use `Option.Option<string>`, while
+ *   optional sections are omitted when they have no entries
+ * - Long names, aliases, and descriptions may require formatter-specific width
+ *   handling when rendering terminal help
+ *
  * @since 4.0.0
  */
 export * as HelpDoc from "./HelpDoc.ts"
 
 /**
- * @internal
+ * The `Param` module defines the shared parser tree used by the unstable CLI
+ * `Argument` and `Flag` modules. A `Param<Kind, A>` describes how to consume
+ * either positional arguments or named flags from parsed command-line input and
+ * return a typed value.
  *
- * Param is the polymorphic implementation shared by Argument.ts and Flag.ts.
- * The `Kind` type parameter ("argument" | "flag") enables type-safe separation
- * while sharing parsing logic and combinators.
+ * **Common tasks**
  *
- * Users should import from `Argument` and `Flag` modules, not this module directly.
- * This module is not exported from the public API.
+ * - Build primitive CLI inputs such as strings, booleans, numbers, choices,
+ *   paths, files, and redacted values
+ * - Attach help metadata with aliases and descriptions
+ * - Transform parsed values with pure or effectful validation
+ * - Model missing inputs with `Option`, defaults, config fallbacks, or prompts
+ * - Accept repeated inputs with variadic, bounded, and non-empty parameters
  *
+ * **Gotchas**
+ *
+ * - The `Kind` type parameter (`"argument"` or `"flag"`) keeps positional
+ *   arguments and flags separate while allowing the implementation and
+ *   combinators to be shared.
+ * - Combinators preserve the parameter kind, so an argument parameter cannot be
+ *   accidentally composed into a flag parameter or the reverse.
+ * - Parsers return both the remaining positional arguments and the parsed
+ *   value; this is important for argument ordering and variadic parameters.
+ * - Some parsers require CLI services such as filesystem, path, terminal, or
+ *   child-process support through the parsing environment.
+ * @internal
  * @since 4.0.0
  */
 export * as Param from "./Param.ts"
@@ -76,6 +251,30 @@ export * as Param from "./Param.ts"
 export * as Primitive from "./Primitive.ts"
 
 /**
+ * The `Prompt` module provides composable, effectful building blocks for
+ * interactive command-line questions. A `Prompt<A>` describes terminal UI that
+ * renders frames, reads keyboard input, validates responses, and eventually
+ * produces a value of type `A`.
+ *
+ * **Common tasks**
+ *
+ * - Ask for text, password, hidden, list, confirm, toggle, number, or date input
+ * - Let users choose from select, autocomplete, multi-select, and file prompts
+ * - Combine prompts with {@link all}, {@link map}, and {@link flatMap}
+ * - Build specialized prompts with {@link custom}
+ * - Run a prompt against the current terminal with {@link run}
+ *
+ * **Gotchas**
+ *
+ * - Prompts require terminal services and may fail with `Terminal.QuitError`
+ *   when input ends or the prompt is quit
+ * - Rendering is frame-based: custom prompts must return ANSI output from
+ *   `render` and matching ANSI clearing output from `clear`
+ * - Choices and file lists are paged by `maxPerPage`, so keyboard navigation
+ *   and filtering should account for hidden off-page entries
+ * - `password` and `hidden` return `Redacted` values; unwrap them only at the
+ *   boundary where the secret is needed
+ *
  * @since 4.0.0
  */
 export * as Prompt from "./Prompt.ts"

package/src/unstable/cli/internal/ansi.ts

@@ -1,3 +1,16 @@
+/**
+ * Internal ANSI escape sequence helpers used by the unstable CLI rendering
+ * implementation. This module centralizes the control codes for text styling,
+ * cursor movement, line erasing, and terminal notifications so renderers can
+ * compose terminal output without scattering raw escape sequences throughout
+ * the CLI internals.
+ *
+ * The helpers deliberately work with plain strings because terminal rendering
+ * is sensitive to ordering: style codes must be reset after annotated text,
+ * cursor operations must account for one-based terminal coordinates, and line
+ * clearing usually needs to preserve the cursor position expected by the next
+ * frame.
+ */
 const ESC = "\x1B["
 const BEL = "\x07"
 const SEP = ";"

package/src/unstable/cli/internal/command.ts

@@ -283,7 +283,11 @@ const parseParams: (parsedArgs: Param.ParsedArgs, params: ReadonlyArray<Param.An
 })
 
 /**
- * Checks for duplicate flag names between parent and child commands.
+ * Checks that inherited parent context flags do not reuse names declared by
+ * child command flags.
+ *
+ * When `contextConfig` is supplied, it is used as the inherited flag set;
+ * otherwise the parent's current context config is checked.
  */
 export const checkForDuplicateFlags = <Name extends string, Input, ContextInput, E, R>(
   parent: Command<Name, Input, ContextInput, E, R>,

package/src/unstable/cli/internal/config.ts

@@ -78,6 +78,9 @@ export interface ConfigInternal {
 }
 
 /**
+ * Namespace containing the tree and node types used to reconstruct parsed
+ * command configuration values.
+ *
  * @since 4.0.0
  */
 export declare namespace ConfigInternal {

package/src/unstable/cli/internal/lexer.ts

@@ -1,3 +1,14 @@
+/**
+ * The lexer module converts raw command-line arguments into the token stream
+ * consumed by the unstable CLI parser. It recognizes long options
+ * (`--name` / `--name=value`), short options (`-x`), clustered short options
+ * (`-abc`), option values supplied with `=`, and positional values.
+ *
+ * The `--` delimiter is handled before tokenization: everything after it is
+ * returned as trailing operands so values that look like options are preserved
+ * exactly. A lone `-` is also preserved as a value instead of being interpreted
+ * as an option.
+ */
 /** @internal */
 export type Token =
   | { _tag: "LongOption"; name: string; raw: string; value?: string }

package/src/unstable/cli/internal/parser.ts

@@ -227,7 +227,6 @@ const makeCursor = (tokens: ReadonlyArray<Token>): TokenCursor => {
 
 /**
  * Creates a registry for O(1) flag lookup by name or alias.
- * @throws Error if duplicate names or aliases are detected (developer error)
  * @internal
  */
 export const createFlagRegistry = (params: ReadonlyArray<FlagParam>): FlagRegistry => {

package/src/unstable/cluster/ClusterCron.ts

@@ -1,4 +1,32 @@
 /**
+ * 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
  */
 import * as Cron from "../../Cron.ts"
@@ -21,8 +49,14 @@ import type { Sharding } from "./Sharding.ts"
 import * as Singleton from "./Singleton.ts"
 
 /**
+ * Creates a layer that runs a cron job through the cluster sharding system.
+ *
+ * The job is scheduled as persisted entity messages, with an initial singleton
+ * scheduling step and optional controls for shard group, next-run calculation,
+ * and skipping stale scheduled runs.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const make = <E, R>(options: {
   readonly name: string

package/src/unstable/cluster/ClusterError.ts

@@ -1,4 +1,25 @@
 /**
+ * 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
  */
 import * as Cause from "../../Cause.ts"
@@ -15,8 +36,8 @@ const TypeId = "~effect/cluster/ClusterError"
  * Represents an error that occurs when a Runner receives a message for an entity
  * that it is not assigned to it.
  *
- * @since 4.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class EntityNotAssignedToRunner
   extends Schema.ErrorClass<EntityNotAssignedToRunner>(`${TypeId}/EntityNotAssignedToRunner`)({
@@ -25,11 +46,15 @@ export class EntityNotAssignedToRunner
   })
 {
   /**
+   * Marks this value as a cluster error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Returns `true` when the value is an `EntityNotAssignedToRunner` error.
+   *
    * @since 4.0.0
    */
   static is(u: unknown): u is EntityNotAssignedToRunner {
@@ -41,19 +66,23 @@ export class EntityNotAssignedToRunner
  * Represents an error that occurs when a message fails to be properly
  * deserialized by an entity.
  *
- * @since 4.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class MalformedMessage extends Schema.ErrorClass<MalformedMessage>(`${TypeId}/MalformedMessage`)({
   _tag: Schema.tag("MalformedMessage"),
   cause: Schema.Defect
 }) {
   /**
+   * Marks this value as a cluster error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Returns `true` when the value is a `MalformedMessage` error.
+   *
    * @since 4.0.0
    */
   static is(u: unknown): u is MalformedMessage {
@@ -61,6 +90,8 @@ export class MalformedMessage extends Schema.ErrorClass<MalformedMessage>(`${Typ
   }
 
   /**
+   * Maps failures from the supplied effect into `MalformedMessage` errors.
+   *
    * @since 4.0.0
    */
   static refail: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<
@@ -74,19 +105,23 @@ export class MalformedMessage extends Schema.ErrorClass<MalformedMessage>(`${Typ
  * Represents an error that occurs when a message fails to be persisted into
  * cluster's mailbox storage.
  *
- * @since 4.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class PersistenceError extends Schema.ErrorClass<PersistenceError>(`${TypeId}/PersistenceError`)({
   _tag: Schema.tag("PersistenceError"),
   cause: Schema.Defect
 }) {
   /**
+   * Marks this value as a cluster error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Maps failures from the supplied effect into `PersistenceError` values.
+   *
    * @since 4.0.0
    */
   static refail<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, PersistenceError, R> {
@@ -98,14 +133,16 @@ export class PersistenceError extends Schema.ErrorClass<PersistenceError>(`${Typ
  * Represents an error that occurs when a Runner is not registered with the shard
  * manager.
  *
- * @since 4.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class RunnerNotRegistered extends Schema.ErrorClass<RunnerNotRegistered>(`${TypeId}/RunnerNotRegistered`)({
   _tag: Schema.tag("RunnerNotRegistered"),
   address: RunnerAddress
 }) {
   /**
+   * Marks this value as a cluster error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
@@ -114,19 +151,23 @@ export class RunnerNotRegistered extends Schema.ErrorClass<RunnerNotRegistered>(
 /**
  * Represents an error that occurs when a Runner is unresponsive.
  *
- * @since 4.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class RunnerUnavailable extends Schema.ErrorClass<RunnerUnavailable>(`${TypeId}/RunnerUnavailable`)({
   _tag: Schema.tag("RunnerUnavailable"),
   address: RunnerAddress
 }) {
   /**
+   * Marks this value as a cluster error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Returns `true` when the value is a `RunnerUnavailable` error.
+   *
    * @since 4.0.0
    */
   static is(u: unknown): u is RunnerUnavailable {
@@ -137,19 +178,23 @@ export class RunnerUnavailable extends Schema.ErrorClass<RunnerUnavailable>(`${T
 /**
  * Represents an error that occurs when the entities mailbox is full.
  *
- * @since 4.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class MailboxFull extends Schema.ErrorClass<MailboxFull>(`${TypeId}/MailboxFull`)({
   _tag: Schema.tag("MailboxFull"),
   address: EntityAddress
 }) {
   /**
+   * Marks this value as a cluster error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Returns `true` when the value is a `MailboxFull` error.
+   *
    * @since 4.0.0
    */
   static is(u: unknown): u is MailboxFull {
@@ -161,8 +206,8 @@ export class MailboxFull extends Schema.ErrorClass<MailboxFull>(`${TypeId}/Mailb
  * Represents an error that occurs when the entity is already processing a
  * request.
  *
- * @since 4.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class AlreadyProcessingMessage
   extends Schema.ErrorClass<AlreadyProcessingMessage>(`${TypeId}/AlreadyProcessingMessage`)({
@@ -172,11 +217,15 @@ export class AlreadyProcessingMessage
   })
 {
   /**
+   * Marks this value as a cluster error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Returns `true` when the value is an `AlreadyProcessingMessage` error.
+   *
    * @since 4.0.0
    */
   static is(u: unknown): u is AlreadyProcessingMessage {

package/src/unstable/cluster/ClusterMetrics.ts

@@ -1,34 +1,68 @@
 /**
+ * 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
  */
 import * as Metric from "../../Metric.ts"
 
 /**
- * @since 4.0.0
+ * Gauge tracking the number of active entity instances for each entity type on
+ * the current runner.
+ *
  * @category metrics
+ * @since 4.0.0
  */
 export const entities = Metric.gauge("effect_cluster_entities", { bigint: true })
 
 /**
- * @since 4.0.0
+ * Gauge tracking the number of singleton processes currently running on the
+ * current runner.
+ *
  * @category metrics
+ * @since 4.0.0
  */
 export const singletons = Metric.gauge("effect_cluster_singletons", { bigint: true })
 
 /**
- * @since 4.0.0
+ * Gauge tracking the number of registered cluster runners.
+ *
  * @category metrics
+ * @since 4.0.0
  */
 export const runners = Metric.gauge("effect_cluster_runners", { bigint: true })
 
 /**
- * @since 4.0.0
+ * Gauge tracking the number of cluster runners currently considered healthy.
+ *
  * @category metrics
+ * @since 4.0.0
  */
 export const runnersHealthy = Metric.gauge("effect_cluster_runners_healthy", { bigint: true })
 
 /**
- * @since 4.0.0
+ * Gauge tracking the number of shards currently acquired by the current runner.
+ *
  * @category metrics
+ * @since 4.0.0
  */
 export const shards = Metric.gauge("effect_cluster_shards", { bigint: true })