effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/unstable/cli/Command.ts

@@ -1,31 +1,12 @@
 /**
- * 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.
+ * Main building block for defining and running Effect-based command-line
+ * applications.
+ *
+ * A `Command` combines a name, typed flags and positional arguments, optional
+ * subcommands, help metadata, and an effectful handler. The module includes
+ * builders for command trees and the runners that parse command-line input,
+ * handle built-in help and version behavior, render help through `CliOutput`,
+ * and execute the selected handler.
  *
  * @since 4.0.0
  */

package/src/unstable/cli/Completions.ts

@@ -4,30 +4,6 @@
  * low-level script generation surface used by the unstable CLI package and by
  * the built-in completions global flag.
  *
- * **Mental model**
- *
- * - {@link CommandDescriptor} is a shell-agnostic tree of commands,
- *   subcommands, flags, and positional arguments.
- * - {@link FlagDescriptor} and {@link ArgumentDescriptor} carry just enough
- *   metadata for shells to complete names, choices, paths, and value-shaped
- *   arguments.
- * - {@link generate} selects the shell-specific generator and returns a static
- *   script string for one executable name.
- *
- * **Common tasks**
- *
- * - Generate an installable completion script with {@link generate}.
- * - Preserve help text in completions by filling descriptor descriptions.
- * - Use `Choice` descriptors for finite values and `Path` descriptors when the
- *   shell should complete files or directories.
- *
- * **Gotchas**
- *
- * - This module does not inspect a `Command` directly; it consumes an already
- *   built {@link CommandDescriptor}.
- * - Generated scripts are returned as strings. Printing, installing, or caching
- *   those scripts is handled by the caller.
- *
  * @since 4.0.0
  */
 import * as Bash from "./internal/completions/bash.ts"

package/src/unstable/cli/Flag.ts

@@ -1,22 +1,12 @@
 /**
- * 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.
+ * Defines named options for command-line applications.
+ *
+ * A `Flag<A>` describes how to read one named value from parsed command-line
+ * input, validate it, and produce an `A`. Flags are useful for inputs such as
+ * ports, verbosity switches, configuration files, output directories, choices,
+ * secrets, and repeated values. The helpers here build flags with aliases,
+ * defaults, optional values, prompts, configuration fallbacks, validation, and
+ * value transformations.
  *
  * @since 4.0.0
  */

package/src/unstable/cli/GlobalFlag.ts

@@ -1,26 +1,12 @@
 /**
- * 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.
+ * Global flags for Effect CLI command trees. Global flags are parsed outside a
+ * single command's local flags and can apply to a command and its descendants.
  *
- * **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
+ * This module defines two kinds of global flags: action flags, which run an
+ * effect and stop normal command execution, and setting flags, which provide a
+ * parsed value to the command handler through the Effect context. It also
+ * defines the built-in help, version, shell-completion, and log-level flags
+ * used by `Command.run` and `Command.runWith`.
  *
  * @since 4.0.0
  */
@@ -217,6 +203,7 @@ export const Completions: Action<Option.Option<"bash" | "zsh" | "fish">> = actio
     .pipe(
       Flag.optional,
       Flag.map((v) => Option.map(v, (s) => s === "sh" ? "bash" : s)),
+      Flag.withMetavar("<bash|zsh|fish|sh>"),
       Flag.withDescription("Print shell completion script")
     ),
   run: (shell, { command }) =>
@@ -256,7 +243,8 @@ export const LogLevel: Setting<"log-level", Option.Option<LogLevelType>> = setti
     ] as const
   ).pipe(
     Flag.optional,
-    Flag.withDescription("Sets the minimum log level")
+    Flag.withDescription("Sets the minimum log level"),
+    Flag.withMetavar("<all|trace|debug|info|warn|warning|error|fatal|none>")
   )
 })
 

package/src/unstable/cli/HelpDoc.ts

@@ -1,24 +1,11 @@
 /**
- * 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.
+ * Structured help documentation model for the unstable CLI package. A
+ * `HelpDoc` value captures the user-facing parts of a command, including its
+ * description, usage string, positional arguments, flags, global flags,
+ * subcommands, annotations, 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
+ * This module only defines the data shapes used to describe help. Rendering
+ * that data as terminal text is handled by `CliOutput`.
  *
  * @since 4.0.0
  */

package/src/unstable/cli/Param.ts

@@ -1,29 +1,12 @@
 /**
- * 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.
- *
- * **Common tasks**
- *
- * - 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.
+ * Defines the shared parameter model for CLI arguments and flags.
+ *
+ * A `Param<Kind, A>` describes how to consume parsed command-line input and
+ * return a typed value. The `Kind` decides whether the parameter reads
+ * positional arguments or named flags. `Argument` and `Flag` build on this
+ * module to share parsing structure, primitive constructors, help metadata,
+ * aliases, defaults, prompts, configuration fallbacks, validation, schema
+ * decoding, fallback parameters, and traversal helpers.
  *
  * @since 4.0.0
  */

package/src/unstable/cli/Primitive.ts

@@ -1,62 +1,12 @@
 /**
- * The `Primitive` module defines the lowest-level value parsers used by the
- * unstable CLI package. A `Primitive<A>` takes one raw command-line string and
- * returns an `Effect` that either produces an `A` or fails with a parser
- * message.
- *
- * `Argument` and `Flag` build on primitives to add names, aliases, defaults,
- * prompts, config fallbacks, repetition, and help metadata. Use this module
- * directly when defining a custom CLI input shape or when composing parser
- * behavior before it becomes an argument or flag.
- *
- * **Mental model**
- *
- * - A primitive parses one value token; it does not know whether the token came
- *   from a positional argument or a named flag.
- * - Parsing may be pure, such as {@link string}, {@link integer},
- *   {@link boolean}, or {@link choice}, or effectful, such as {@link path},
- *   {@link fileText}, {@link fileParse}, and {@link fileSchema}.
- * - Failure is represented as a string message so higher-level CLI parsers can
- *   attach it to generated usage and help output.
- * - File and path primitives require filesystem and path services through the
- *   parsing effect environment.
- *
- * **Common tasks**
- *
- * - Parse scalar values with {@link string}, {@link integer}, {@link float},
- *   {@link boolean}, and {@link date}.
- * - Restrict input to named alternatives with {@link choice}.
- * - Resolve and validate filesystem paths with {@link path}.
- * - Read raw file content with {@link fileText}, parse structured files with
- *   {@link fileParse}, or decode parsed content with {@link fileSchema}.
- * - Hide sensitive input with {@link redacted}.
- * - Parse `key=value` entries with {@link keyValuePair}.
- *
- * **Example** (Parsing raw CLI values)
- *
- * ```ts
- * import { Effect } from "effect"
- * import { Primitive } from "effect/unstable/cli"
- *
- * const parseValues = Effect.gen(function*() {
- *   const port = yield* Primitive.integer.parse("8080")
- *   const mode = yield* Primitive.choice([
- *     ["dev", "development"],
- *     ["prod", "production"]
- *   ] as const).parse("prod")
- *
- *   return { port, mode }
- * })
- * ```
- *
- * **Gotchas**
- *
- * - `choice` matches input strings exactly; it does not normalize casing or
- *   trim whitespace.
- * - `fileParse` selects a parser from `options.format` or the file extension;
- *   unsupported formats fail before schema decoding.
- * - {@link none} is a sentinel parser that always fails. It is used by higher
- *   layers for parameters that must reject attached values.
+ * Parses raw command-line strings into typed values.
+ *
+ * A `Primitive<A>` receives one string and returns an `Effect` that either
+ * produces an `A` or fails with a parser message. `Argument` and `Flag` build
+ * on these primitives to add names, aliases, defaults, prompts, configuration
+ * fallbacks, repetition, and help metadata. Primitive parsers cover common
+ * scalar values, paths, files, structured config files, schema-decoded input,
+ * redacted values, and key-value pairs.
  *
  * @since 4.0.0
  */

package/src/unstable/cli/Prompt.ts

@@ -1,27 +1,12 @@
 /**
- * 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
+ * Builds interactive terminal prompts for CLI applications.
+ *
+ * A `Prompt<A>` describes a small terminal UI that renders frames, reads
+ * keyboard input, validates responses, and eventually produces an `A`. Prompts
+ * can ask for simple values, selections, lists, files, hidden text, or custom
+ * interactions. This module includes prompt constructors, tools for combining
+ * and transforming prompt output, and support for running prompts through the
+ * `Terminal` service.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/ClusterCron.ts

@@ -1,31 +1,11 @@
 /**
- * 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.
+ * Runs recurring cron jobs through cluster sharding.
  *
- * 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.
+ * This module turns a `Cron.Cron` schedule into a `Layer` that coordinates one
+ * recurring job across a cluster. It registers a singleton for the initial
+ * scheduling step and a persisted entity message for each run. This is useful
+ * for distributed maintenance work where the job should be owned by the cluster
+ * rather than by every runner independently.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/ClusterError.ts

@@ -1,45 +1,10 @@
 /**
- * The `ClusterError` module defines the tagged, schema-backed error values used
- * by the unstable cluster runtime. These errors describe failures at routing,
- * runner membership, serialization, persistence, mailbox capacity, and duplicate
- * envelope boundaries.
+ * Defines the structured errors used by the unstable cluster runtime.
  *
- * **Mental model**
- *
- * - Cluster operations fail with typed values so callers can distinguish retry,
- *   supervision, decoding, and storage failures.
- * - Each error has a stable `_tag` and schema representation for transport or
- *   storage boundaries.
- * - Static `is` helpers recognize errors from this module at runtime, and
- *   `refail` helpers map lower-level failures into cluster errors.
- *
- * **Common tasks**
- *
- * - Report wrong-runner delivery with {@link EntityNotAssignedToRunner}.
- * - Surface runner membership and liveness failures with
- *   {@link RunnerNotRegistered} or {@link RunnerUnavailable}.
- * - Convert encode and decode failures to {@link MalformedMessage}.
- * - Preserve storage failures as {@link PersistenceError}.
- * - Signal mailbox pressure with {@link MailboxFull}.
- * - Reject duplicate in-flight envelopes with
- *   {@link AlreadyProcessingMessage}.
- *
- * **Gotchas**
- *
- * - Ownership and health can change while a message is in flight, so routing
- *   and availability errors are often retryable by higher-level cluster logic.
- * - {@link MalformedMessage} means the payload crossed a schema or
- *   serialization boundary incorrectly; it is not an entity handler failure.
- * - {@link AlreadyProcessingMessage} is per-envelope protection, not a general
- *   entity lock.
- *
- * **See also**
- *
- * - {@link EntityNotAssignedToRunner}, {@link RunnerUnavailable}, and
- *   {@link RunnerNotRegistered} for routing and membership failures.
- * - {@link MalformedMessage} and {@link PersistenceError} for boundary
- *   failures.
- * - {@link MailboxFull} and {@link AlreadyProcessingMessage} for mailbox state.
+ * These tagged, schema-backed errors describe failures at routing, runner
+ * membership, serialization, persistence, mailbox capacity, and duplicate
+ * envelope boundaries. Cluster clients, runners, and storage adapters use these
+ * shared error values to report failures through typed Effect errors.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/ClusterMetrics.ts

@@ -1,25 +1,11 @@
 /**
- * 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.
+ * Standard metric definitions used by the unstable cluster runtime. The gauges
+ * track runner-local entities, singleton processes, registered runners,
+ * healthy runners, and acquired shards.
  *
- * **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
+ * This module only defines the metric handles. The runtime components that
+ * manage entities, runners, singletons, and sharding update these gauges while
+ * the cluster is running.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/ClusterSchema.ts

@@ -4,44 +4,6 @@
  * requests are persisted, handled in transactions, interrupted, traced, and
  * routed to shard groups without changing the request or response schema.
  *
- * **Mental model**
- *
- * - An annotation is protocol metadata read by the cluster runtime.
- * - Static annotations apply to every request covered by the annotated RPC or
- *   entity.
- * - {@link Dynamic} can adjust server-side annotations from the decoded request
- *   that is already part of the protocol.
- *
- * **Common tasks**
- *
- * - Mark requests for durable mailbox storage with {@link Persisted}.
- * - Wrap server handling and storage work in the configured storage transaction
- *   with {@link WithTransaction}.
- * - Decide whether client sending, server handling, or both ignore interruption
- *   with {@link Uninterruptible}.
- * - Route entity ids into shard groups with {@link ShardGroup}.
- * - Disable client tracing for internal or high-volume protocols with
- *   {@link ClientTracingEnabled}.
- * - Derive request annotations from the request value with {@link Dynamic}.
- *
- * **Gotchas**
- *
- * - Persisted requests require message storage that can save mailbox messages
- *   and replies.
- * - {@link WithTransaction} only has transactional behavior when the configured
- *   storage layer implements transactions.
- * - Shard group functions must be deterministic for the same entity id across
- *   all runners that share a cluster.
- * - {@link Dynamic} affects entity-side request handling, not the generated
- *   client.
- *
- * **See also**
- *
- * - {@link Persisted}, {@link WithTransaction}, and {@link Uninterruptible} for
- *   delivery and handling behavior.
- * - {@link ShardGroup} for shard-group selection.
- * - {@link Dynamic} for deriving annotations from a request.
- *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"

package/src/unstable/cluster/ClusterWorkflowEngine.ts

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

package/src/unstable/cluster/DeliverAt.ts

@@ -4,23 +4,6 @@
  * 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
  */
 import type { DateTime } from "../../DateTime.ts"

package/src/unstable/cluster/Entity.ts

@@ -1,35 +1,12 @@
 /**
- * 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
+ * Defines addressable entity types for Effect Cluster.
+ *
+ * An entity gives a stable name and RPC protocol to a group of values that are
+ * addressed by id. The cluster uses that information to choose a shard and
+ * route each request to the runner responsible for that id. This module
+ * includes constructors for entity definitions, helpers for creating sharded
+ * clients, layer builders for registering handlers, and services that expose
+ * the current entity address while a request is being handled.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/EntityAddress.ts

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