effect 4.0.0-beta.66 → 4.0.0-beta.67

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
@@ -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)) {