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

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

@@ -8,9 +8,8 @@
 import * as Arr from "../../../Array.ts"
 import * as Context from "../../../Context.ts"
 import * as Effect from "../../../Effect.ts"
-import { YieldableProto } from "../../../internal/core.ts"
+import * as Effectable from "../../../Effectable.ts"
 import * as Option from "../../../Option.ts"
-import { pipeArguments } from "../../../Pipeable.ts"
 import * as Predicate from "../../../Predicate.ts"
 import * as CliError from "../CliError.ts"
 import type * as GlobalFlag from "../GlobalFlag.ts"
@@ -73,14 +72,13 @@ export const toImpl = <Name extends string, Input, E, R, ContextInput = {}>(
 /* Proto                                                                      */
 /* ========================================================================== */
 
-export const Proto = {
-  ...YieldableProto,
-  pipe() {
-    return pipeArguments(this, arguments)
-  },
-  asEffect(this: Command<any, any, any, any, any>) {
-    return toImpl(this).service.asEffect()
-  }
+export const Proto: Effect.Effect<any, never, any> = {
+  ...Effectable.Prototype<Command.Any>({
+    label: "Command",
+    evaluate() {
+      return toImpl(this).service
+    }
+  })
 }
 
 /* ========================================================================== */
@@ -285,11 +283,15 @@ 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>(
-  parent: Command<Name, Input, ContextInput, unknown, unknown>,
-  subcommands: ReadonlyArray<Command<any, unknown, any, unknown, unknown>>,
+export const checkForDuplicateFlags = <Name extends string, Input, ContextInput, E, R>(
+  parent: Command<Name, Input, ContextInput, E, R>,
+  subcommands: ReadonlyArray<Command.Any>,
   options?: {
     readonly contextConfig?: ConfigInternal | undefined
   } | undefined
@@ -309,7 +311,7 @@ export const checkForDuplicateFlags = <Name extends string, Input, ContextInput>
   extractNames((options?.contextConfig ?? parentImpl.contextConfig).flags)
 
   for (const subcommand of subcommands) {
-    const subImpl = toImpl(subcommand)
+    const subImpl = toImpl(subcommand as any)
     for (const option of subImpl.config.flags) {
       const singles = Param.extractSingleParams(option)
       for (const single of singles) {

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/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"
 
 /**
- * @since 4.0.0
+ * 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
  */
 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 })

package/src/unstable/cluster/ClusterSchema.ts

@@ -1,4 +1,30 @@
 /**
+ * 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.
+ *
+ * **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.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -8,8 +34,13 @@ import type { EntityId } from "./EntityId.ts"
 import type { Request } from "./Envelope.ts"
 
 /**
- * @since 4.0.0
+ * Annotation that marks whether a cluster request should be persisted in mailbox
+ * storage.
+ *
+ * The default value is `false`.
+ *
  * @category Annotations
+ * @since 4.0.0
  */
 export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchema/Persisted", {
   defaultValue: constFalse
@@ -19,8 +50,8 @@ export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchem
  * Whether to wrap the request with a storage transaction, so sql queries are
  * committed atomically.
  *
- * @since 4.0.0
  * @category Annotations
+ * @since 4.0.0
  */
 export const WithTransaction = Context.Reference<boolean>(
   "effect/cluster/ClusterSchema/WithTransaction",
@@ -28,8 +59,15 @@ export const WithTransaction = Context.Reference<boolean>(
 )
 
 /**
- * @since 4.0.0
+ * Annotation that controls whether a cluster request is treated as
+ * uninterruptible.
+ *
+ * Use `true` for both client and server handling, `"client"` for client-side
+ * handling only, `"server"` for server-side handling only, or `false` to allow
+ * interruption.
+ *
  * @category Annotations
+ * @since 4.0.0
  */
 export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
   "effect/cluster/ClusterSchema/Uninterruptible",
@@ -37,8 +75,11 @@ export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
 )
 
 /**
- * @since 4.0.0
+ * Returns whether the `Uninterruptible` annotation applies to server-side
+ * request handling for the provided context.
+ *
  * @category Annotations
+ * @since 4.0.0
  */
 export const isUninterruptibleForServer = (context: Context.Context<never>): boolean => {
   const value = Context.get(context, Uninterruptible)
@@ -46,8 +87,11 @@ export const isUninterruptibleForServer = (context: Context.Context<never>): boo
 }
 
 /**
- * @since 4.0.0
+ * Returns whether the `Uninterruptible` annotation applies to client-side
+ * request handling for the provided context.
+ *
  * @category Annotations
+ * @since 4.0.0
  */
 export const isUninterruptibleForClient = (context: Context.Context<never>): boolean => {
   const value = Context.get(context, Uninterruptible)
@@ -55,8 +99,12 @@ export const isUninterruptibleForClient = (context: Context.Context<never>): boo
 }
 
 /**
- * @since 4.0.0
+ * Annotation that selects the shard group for an entity id.
+ *
+ * By default, every entity id is assigned to the `"default"` shard group.
+ *
  * @category Annotations
+ * @since 4.0.0
  */
 export const ShardGroup = Context.Reference<(entityId: EntityId) => string>(
   "effect/cluster/ClusterSchema/ShardGroup",
@@ -64,8 +112,13 @@ export const ShardGroup = Context.Reference<(entityId: EntityId) => string>(
 )
 
 /**
- * @since 4.0.0
+ * Annotation that controls whether client-side cluster request tracing is
+ * enabled.
+ *
+ * The default value is `true`.
+ *
  * @category Annotations
+ * @since 4.0.0
  */
 export const ClientTracingEnabled = Context.Reference<boolean>("effect/cluster/ClusterSchema/ClientTracingEnabled", {
   defaultValue: constTrue
@@ -75,8 +128,8 @@ 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.
  *
- * @since 4.0.0
  * @category Annotations
+ * @since 4.0.0
  */
 export const Dynamic = Context.Reference<
   (annotations: Context.Context<never>, request: Request<Rpc.AnyWithProps>) => Context.Context<never>

package/src/unstable/cluster/ClusterWorkflowEngine.ts

@@ -1,4 +1,25 @@
 /**
+ * The cluster workflow engine runs durable workflows on top of cluster sharding
+ * and message storage. It adapts `WorkflowEngine.WorkflowEngine` so workflow
+ * 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"
@@ -38,8 +59,14 @@ import * as Sharding from "./Sharding.ts"
 import * as Snowflake from "./Snowflake.ts"
 
 /**
- * @since 4.0.0
+ * Creates a `WorkflowEngine` implementation backed by cluster sharding and
+ * message storage.
+ *
+ * Workflow executions, activities, deferred completions, resumes, interrupts,
+ * and durable clock wakeups are coordinated through persisted cluster entities.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = Effect.gen(function*() {
   const sharding = yield* Sharding.Sharding
@@ -502,7 +529,7 @@ export const make = Effect.gen(function*() {
     ),
 
     deferredResult: (deferred) =>
-      WorkflowEngine.WorkflowInstance.asEffect().pipe(
+      WorkflowEngine.WorkflowInstance.pipe(
         Effect.flatMap((instance) =>
           requestReply({
             workflow: instance.workflow,
@@ -693,8 +720,14 @@ const ClockEntityLayer = ClockEntity.toLayer(Effect.gen(function*() {
 const InterruptSignal = DurableDeferred.make("Workflow/InterruptSignal")
 
 /**
- * @since 4.0.0
+ * Layer that provides `WorkflowEngine.WorkflowEngine` using the cluster workflow
+ * engine implementation.
+ *
+ * It requires cluster sharding and message storage, and also registers the
+ * durable clock entity used for workflow wakeups.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<
   WorkflowEngine.WorkflowEngine,

package/src/unstable/cluster/DeliverAt.ts

@@ -1,32 +1,67 @@
 /**
+ * The `DeliverAt` module defines the protocol used by cluster message payloads
+ * that carry their own scheduled delivery time. A value implements the protocol
+ * 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"
 import { hasProperty } from "../../Predicate.ts"
 
 /**
- * @since 4.0.0
+ * Property key used by values that provide a scheduled delivery time.
+ *
  * @category symbols
+ * @since 4.0.0
  */
 export const symbol = "~effect/cluster/DeliverAt"
 
 /**
- * @since 4.0.0
+ * Interface for payloads that specify when a cluster message should be delivered.
+ *
+ * Implementations return the target delivery `DateTime` through the `DeliverAt`
+ * symbol method.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface DeliverAt {
   [symbol](): DateTime
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` if the value implements the `DeliverAt` scheduled-delivery
+ * protocol.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isDeliverAt = (self: unknown): self is DeliverAt => hasProperty(self, symbol)
 
 /**
- * @since 4.0.0
+ * Returns the scheduled delivery time in epoch milliseconds when the value
+ * implements `DeliverAt`, or `null` otherwise.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const toMillis = (self: unknown): number | null => {
   if (isDeliverAt(self)) {