effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/cli/index.ts

@@ -5,276 +5,56 @@
 // @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"
 
 /**
- * Shell completion descriptors and script generation for the unstable CLI API.
- *
  * @since 4.0.0
  */
 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"
 
 /**
- * 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.
- *
  * @since 4.0.0
  */
 export * as Param from "./Param.ts"
 
 /**
- * Primitive types for CLI parameter parsing.
- *
- * Primitives handle the low-level parsing of string input into typed values.
- * Most users should use the higher-level `Argument` and `Flag` modules instead.
- *
- * This module is primarily useful for:
- * - Creating custom primitive types
- * - Understanding how CLI parsing works internally
- * - Advanced customization of parsing behavior
- *
  * @since 4.0.0
  */
 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/parser.ts

@@ -381,7 +381,7 @@ const invalidNegatedFlagValue = (
   })
 
 /**
- * Checks if a token is a boolean literal value.
+ * Checks whether a token is a boolean literal value.
  * Recognizes: true/false, yes/no, on/off, 1/0
  */
 const asBooleanLiteral = (token: Token | undefined): string | undefined =>

package/src/unstable/cluster/ClusterCron.ts

@@ -87,7 +87,7 @@ export const make = <E, R>(options: {
    *
    * **When to use**
    *
-   * This is useful to prevent running jobs that were scheduled too far in the
+   * Use when this is useful to prevent running jobs that were scheduled too far in the
    * past.
    *
    * **Details**

package/src/unstable/cluster/ClusterError.ts

@@ -1,24 +1,45 @@
 /**
- * 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.
+ * 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.
  *
- * 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.
+ * **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**
  *
- * - 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.
+ * - 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.
  *
  * @since 4.0.0
  */
@@ -34,7 +55,7 @@ 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.
+ * that is not assigned to the receiving runner.
  *
  * @category errors
  * @since 4.0.0
@@ -63,8 +84,13 @@ export class EntityNotAssignedToRunner
 }
 
 /**
- * Represents an error that occurs when a message fails to be properly
- * deserialized by an entity.
+ * Represents an error that occurs when a message fails at a schema
+ * serialization or deserialization boundary.
+ *
+ * **Details**
+ *
+ * `cause` carries the underlying failure. `refail` maps encode and decode
+ * failures into `MalformedMessage` values.
  *
  * @category errors
  * @since 4.0.0
@@ -176,7 +202,16 @@ export class RunnerUnavailable extends Schema.ErrorClass<RunnerUnavailable>(`${T
 }
 
 /**
- * Represents an error that occurs when the entities mailbox is full.
+ * Represents an error that occurs when the entity mailbox is full.
+ *
+ * **Details**
+ *
+ * Carries the `address` whose bounded mailbox is at capacity.
+ *
+ * **Gotchas**
+ *
+ * Volatile requests fail immediately. Persisted or durable messages are retried
+ * or resumed from storage when the mailbox is full.
  *
  * @category errors
  * @since 4.0.0
@@ -203,8 +238,12 @@ export class MailboxFull extends Schema.ErrorClass<MailboxFull>(`${TypeId}/Mailb
 }
 
 /**
- * Represents an error that occurs when the entity is already processing a
- * request.
+ * Represents an error that occurs when the same request envelope is already
+ * being processed.
+ *
+ * **Details**
+ *
+ * Carries the `address` and `envelopeId` for the affected request envelope.
  *
  * @category errors
  * @since 4.0.0

package/src/unstable/cluster/ClusterMetrics.ts

@@ -26,16 +26,29 @@
 import * as Metric from "../../Metric.ts"
 
 /**
- * Gauge tracking the number of active entity instances for each entity type on
+ * Creates a gauge tracking the number of active entity instances for each entity type on
  * the current runner.
  *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_entities`, updated with the entity type as
+ * a metric tag.
+ *
+ * **Gotchas**
+ *
+ * This gauge is runner-local and sampled by the entity manager loop. Aggregate
+ * across runners and expect up to roughly one polling interval of lag.
+ *
+ * @see {@link singletons} for singleton process counts on the current runner
+ * @see {@link shards} for shard ownership on the current runner
+ *
  * @category metrics
  * @since 4.0.0
  */
 export const entities = Metric.gauge("effect_cluster_entities", { bigint: true })
 
 /**
- * Gauge tracking the number of singleton processes currently running on the
+ * Creates a gauge tracking the number of singleton processes currently running on the
  * current runner.
  *
  * @category metrics
@@ -44,7 +57,17 @@ export const entities = Metric.gauge("effect_cluster_entities", { bigint: true }
 export const singletons = Metric.gauge("effect_cluster_singletons", { bigint: true })
 
 /**
- * Gauge tracking the number of registered cluster runners.
+ * Represents a gauge tracking the number of registered cluster runners.
+ *
+ * **When to use**
+ *
+ * Use to monitor the registered runners currently known to the cluster runtime.
+ *
+ * **Gotchas**
+ *
+ * The value can lag briefly during membership changes or failure detection.
+ *
+ * @see {@link runnersHealthy} for the healthy-runner subset
  *
  * @category metrics
  * @since 4.0.0
@@ -52,7 +75,22 @@ export const singletons = Metric.gauge("effect_cluster_singletons", { bigint: tr
 export const runners = Metric.gauge("effect_cluster_runners", { bigint: true })
 
 /**
- * Gauge tracking the number of cluster runners currently considered healthy.
+ * Represents a gauge tracking the number of cluster runners currently considered healthy.
+ *
+ * **When to use**
+ *
+ * Use to monitor the healthy subset of registered cluster runners.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_runners_healthy`.
+ *
+ * **Gotchas**
+ *
+ * The value reflects the runtime's health-check view and can lag during
+ * membership changes or failure detection.
+ *
+ * @see {@link runners} for the total registered-runner gauge
  *
  * @category metrics
  * @since 4.0.0
@@ -60,7 +98,22 @@ export const runners = Metric.gauge("effect_cluster_runners", { bigint: true })
 export const runnersHealthy = Metric.gauge("effect_cluster_runners_healthy", { bigint: true })
 
 /**
- * Gauge tracking the number of shards currently acquired by the current runner.
+ * Represents a gauge tracking the number of shards currently acquired by the current runner.
+ *
+ * **When to use**
+ *
+ * Use to observe shard ownership held by the current runner during startup,
+ * rebalancing, or failover.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_shards`, updated from the sharding
+ * acquisition loop using the current acquired shard count.
+ *
+ * **Gotchas**
+ *
+ * This is runner-local, not a cluster-wide shard total. Aggregate per-runner
+ * values carefully.
  *
  * @category metrics
  * @since 4.0.0

package/src/unstable/cluster/ClusterSchema.ts

@@ -1,29 +1,46 @@
 /**
- * The `ClusterSchema` module defines the schema annotations used by Effect
- * Cluster protocols. These annotations attach cluster-specific behavior to
- * RPCs and entities without changing the request or response schemas
- * themselves.
+ * The `ClusterSchema` module collects the annotations that add cluster behavior
+ * to RPC protocols and entity definitions. These annotations describe how
+ * 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 as persisted so mailbox storage can replay them after
- *   interruption or restart
- * - Run server-side handling inside a storage transaction when durable state
- *   and SQL updates must commit together
- * - Control whether client sending, server handling, or both are treated as
- *   uninterruptible
- * - Route entity ids into shard groups
- * - Disable client tracing for internal protocols such as cron dispatch
- * - Derive per-request annotations from the encoded request with {@link Dynamic}
- *
- * **Protocol notes**
- *
- * Cluster transports serialize the RPC payloads, not arbitrary runtime
- * annotation values. Prefer static, deterministic annotations, and use
- * {@link Dynamic} when a persisted or transactional decision depends on the
- * request value that is already part of the protocol. Persisted requests require
- * message storage support, and shard group selection must remain stable for a
- * given entity id so routing is consistent across cluster members.
+ * - 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
  */
@@ -49,8 +66,23 @@ export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchem
 })
 
 /**
- * Whether to wrap the request with a storage transaction, so sql queries are
- * committed atomically.
+ * Annotation that marks whether request handling should be wrapped in the
+ * configured message storage transaction.
+ *
+ * **When to use**
+ *
+ * Use when a request needs server-side handling or storage work wrapped in the
+ * storage transaction.
+ *
+ * **Details**
+ *
+ * The default value is `false`. When `true`, entity handling wraps server
+ * writes with the configured storage transaction.
+ *
+ * **Gotchas**
+ *
+ * This annotation has transactional behavior only when the configured
+ * `MessageStorage` implements it.
  *
  * @category annotations
  * @since 4.0.0
@@ -82,6 +114,13 @@ export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
  * Returns whether the `Uninterruptible` annotation applies to server-side
  * request handling for the provided context.
  *
+ * **Details**
+ *
+ * Returns `true` only when `Uninterruptible` is `true` or `"server"`.
+ *
+ * @see {@link Uninterruptible} for the annotation values interpreted by this helper
+ * @see {@link isUninterruptibleForClient} for the client-side counterpart
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -94,6 +133,19 @@ export const isUninterruptibleForServer = (context: Context.Context<never>): boo
  * Returns whether the `Uninterruptible` annotation applies to client-side
  * request handling for the provided context.
  *
+ * **When to use**
+ *
+ * Use when client-side cluster request handling needs to decide whether an
+ * interrupt should be ignored.
+ *
+ * **Details**
+ *
+ * Returns `true` when `Uninterruptible` is `true` or `"client"`, and `false`
+ * for `"server"` or the default `false`.
+ *
+ * @see {@link Uninterruptible} for the annotation values interpreted by this helper
+ * @see {@link isUninterruptibleForServer} for the server-side counterpart
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -133,8 +185,17 @@ export const ClientTracingEnabled = Context.Reference<boolean>("effect/cluster/C
 })
 
 /**
- * Dynamically transform the request annotations based on the request.
- * This only applies to the requests handled by the Entity, not the client.
+ * Context reference for deriving request annotations from a cluster request.
+ *
+ * **When to use**
+ *
+ * Use to customize server-side request annotations based on the decoded
+ * request value.
+ *
+ * **Gotchas**
+ *
+ * This only applies to requests handled by the entity, not to the generated
+ * client.
  *
  * @category annotations
  * @since 4.0.0