effect 4.0.0-beta.70 → 4.0.0-beta.71

package/dist/unstable/cluster/ClusterError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterError.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ClusterError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAEpD,QAAA,MAAM,MAAM,iCAAiC,CAAA;;;;;AAE7C;;;;;;GAMG;AACH,qBAAa,yBACX,SAAQ,8BAGN;IAEF;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,yBAAyB;CAGtD;;;;;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,qBAGpC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,gBAAgB;IAI5C;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CACvE,CAAC,EACD,gBAAgB,EAChB,CAAC,CACF,CAA8D;CAChE;;;;;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,qBAGpC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;CAG9F;;;;;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,wBAGvC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;CAC3B;;;;;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,sBAGrC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,iBAAiB;CAG9C;;;;;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,gBAG/B;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,WAAW;CAGxC;;;;;;AAED;;;;;;GAMG;AACH,qBAAa,wBACX,SAAQ,6BAIN;IAEF;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,wBAAwB;CAGrD"}
+{"version":3,"file":"ClusterError.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ClusterError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAEpD,QAAA,MAAM,MAAM,iCAAiC,CAAA;;;;;AAE7C;;;;;;GAMG;AACH,qBAAa,yBACX,SAAQ,8BAGN;IAEF;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,yBAAyB;CAGtD;;;;;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,SAAQ,qBAGpC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,gBAAgB;IAI5C;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CACvE,CAAC,EACD,gBAAgB,EAChB,CAAC,CACF,CAA8D;CAChE;;;;;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,qBAGpC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;CAG9F;;;;;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,wBAGvC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;CAC3B;;;;;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,sBAGrC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,iBAAiB;CAG9C;;;;;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAY,SAAQ,gBAG/B;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,WAAW;CAGxC;;;;;;AAED;;;;;;;;;;GAUG;AACH,qBAAa,wBACX,SAAQ,6BAIN;IAEF;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,kCAAS;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,wBAAwB;CAGrD"}

package/dist/unstable/cluster/ClusterError.js

@@ -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
  */
@@ -32,7 +53,7 @@ import { SnowflakeFromString } from "./Snowflake.js";
 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
@@ -57,8 +78,13 @@ export class EntityNotAssignedToRunner extends /*#__PURE__*/Schema.ErrorClass(`$
   }
 }
 /**
- * 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
@@ -162,7 +188,16 @@ export class RunnerUnavailable extends /*#__PURE__*/Schema.ErrorClass(`${TypeId}
   }
 }
 /**
- * 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
@@ -187,8 +222,12 @@ export class MailboxFull extends /*#__PURE__*/Schema.ErrorClass(`${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/dist/unstable/cluster/ClusterError.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterError.js","names":["Cause","Effect","hasProperty","isTagged","Schema","EntityAddress","RunnerAddress","SnowflakeFromString","TypeId","EntityNotAssignedToRunner","ErrorClass","_tag","tag","address","is","u","MalformedMessage","cause","Defect","refail","mapError","PersistenceError","effect","catchCause","fail","squash","RunnerNotRegistered","RunnerUnavailable","MailboxFull","AlreadyProcessingMessage","envelopeId"],"sources":["../../../src/unstable/cluster/ClusterError.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"ClusterError.js","names":["Cause","Effect","hasProperty","isTagged","Schema","EntityAddress","RunnerAddress","SnowflakeFromString","TypeId","EntityNotAssignedToRunner","ErrorClass","_tag","tag","address","is","u","MalformedMessage","cause","Defect","refail","mapError","PersistenceError","effect","catchCause","fail","squash","RunnerNotRegistered","RunnerUnavailable","MailboxFull","AlreadyProcessingMessage","envelopeId"],"sources":["../../../src/unstable/cluster/ClusterError.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/unstable/cluster/ClusterMetrics.d.ts

@@ -28,6 +28,19 @@ import * as Metric from "../../Metric.ts";
  * 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
  */
@@ -43,6 +56,16 @@ export declare const singletons: Metric.Gauge<bigint>;
 /**
  * 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
  */
@@ -50,6 +73,21 @@ export declare const runners: Metric.Gauge<bigint>;
 /**
  * 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
  */
@@ -57,6 +95,21 @@ export declare const runnersHealthy: Metric.Gauge<bigint>;
 /**
  * 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/dist/unstable/cluster/ClusterMetrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterMetrics.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ClusterMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,sBAA4D,CAAA;AAEjF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,sBAA8D,CAAA;AAErF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,sBAA2D,CAAA;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,cAAc,sBAAmE,CAAA;AAE9F;;;;;GAKG;AACH,eAAO,MAAM,MAAM,sBAA0D,CAAA"}
+{"version":3,"file":"ClusterMetrics.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ClusterMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,sBAA4D,CAAA;AAEjF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,sBAA8D,CAAA;AAErF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,sBAA2D,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,cAAc,sBAAmE,CAAA;AAE9F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,MAAM,sBAA0D,CAAA"}

package/dist/unstable/cluster/ClusterMetrics.js

@@ -28,6 +28,19 @@ import * as Metric from "../../Metric.js";
  * 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
  */
@@ -47,6 +60,16 @@ export const singletons = /*#__PURE__*/Metric.gauge("effect_cluster_singletons",
 /**
  * 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
  */
@@ -56,6 +79,21 @@ export const runners = /*#__PURE__*/Metric.gauge("effect_cluster_runners", {
 /**
  * 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
  */
@@ -65,6 +103,21 @@ export const runnersHealthy = /*#__PURE__*/Metric.gauge("effect_cluster_runners_
 /**
  * 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/dist/unstable/cluster/ClusterMetrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterMetrics.js","names":["Metric","entities","gauge","bigint","singletons","runners","runnersHealthy","shards"],"sources":["../../../src/unstable/cluster/ClusterMetrics.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AAEzC;;;;;;;AAOA,OAAO,MAAMC,QAAQ,gBAAGD,MAAM,CAACE,KAAK,CAAC,yBAAyB,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAEjF;;;;;;;AAOA,OAAO,MAAMC,UAAU,gBAAGJ,MAAM,CAACE,KAAK,CAAC,2BAA2B,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAErF;;;;;;AAMA,OAAO,MAAME,OAAO,gBAAGL,MAAM,CAACE,KAAK,CAAC,wBAAwB,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAE/E;;;;;;AAMA,OAAO,MAAMG,cAAc,gBAAGN,MAAM,CAACE,KAAK,CAAC,gCAAgC,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAE9F;;;;;;AAMA,OAAO,MAAMI,MAAM,gBAAGP,MAAM,CAACE,KAAK,CAAC,uBAAuB,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC","ignoreList":[]}
+{"version":3,"file":"ClusterMetrics.js","names":["Metric","entities","gauge","bigint","singletons","runners","runnersHealthy","shards"],"sources":["../../../src/unstable/cluster/ClusterMetrics.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AAEzC;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMC,QAAQ,gBAAGD,MAAM,CAACE,KAAK,CAAC,yBAAyB,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAEjF;;;;;;;AAOA,OAAO,MAAMC,UAAU,gBAAGJ,MAAM,CAACE,KAAK,CAAC,2BAA2B,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAErF;;;;;;;;;;;;;;;;AAgBA,OAAO,MAAME,OAAO,gBAAGL,MAAM,CAACE,KAAK,CAAC,wBAAwB,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMG,cAAc,gBAAGN,MAAM,CAACE,KAAK,CAAC,gCAAgC,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMI,MAAM,gBAAGP,MAAM,CAACE,KAAK,CAAC,uBAAuB,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC","ignoreList":[]}

package/dist/unstable/cluster/ClusterSchema.d.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
  */
@@ -44,8 +61,23 @@ import type { Request } from "./Envelope.ts";
  */
 export declare const Persisted: Context.Reference<boolean>;
 /**
- * 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
@@ -69,6 +101,13 @@ export declare const Uninterruptible: Context.Reference<boolean | "server" | "cl
  * 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
  */
@@ -77,6 +116,19 @@ export declare const isUninterruptibleForServer: (context: Context.Context<never
  * 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
  */

package/dist/unstable/cluster/ClusterSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterSchema.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ClusterSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAE3C,OAAO,KAAK,KAAK,GAAG,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE5C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,4BAEpB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,4BAG3B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,kDAG3B,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,OAG5E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,OAG5E,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,+BAAgC,QAAQ,KAAK,MAAM,CAGzE,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,4BAE/B,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,kCACJ,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAIpG,CAAA"}
+{"version":3,"file":"ClusterSchema.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ClusterSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAE3C,OAAO,KAAK,KAAK,GAAG,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE5C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,4BAEpB,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,4BAG3B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,kDAG3B,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,OAG5E,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,OAG5E,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,+BAAgC,QAAQ,KAAK,MAAM,CAGzE,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,4BAE/B,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,kCACJ,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAIpG,CAAA"}

package/dist/unstable/cluster/ClusterSchema.js

@@ -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
  */
@@ -44,8 +61,23 @@ export const Persisted = /*#__PURE__*/Context.Reference("effect/cluster/ClusterS
   defaultValue: constFalse
 });
 /**
- * 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
@@ -73,6 +105,13 @@ export const Uninterruptible = /*#__PURE__*/Context.Reference("effect/cluster/Cl
  * 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
  */
@@ -84,6 +123,19 @@ export const isUninterruptibleForServer = context => {
  * 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
  */

package/dist/unstable/cluster/ClusterSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterSchema.js","names":["Context","constFalse","constTrue","identity","Persisted","Reference","defaultValue","WithTransaction","Uninterruptible","isUninterruptibleForServer","context","value","get","isUninterruptibleForClient","ShardGroup","_","ClientTracingEnabled","Dynamic"],"sources":["../../../src/unstable/cluster/ClusterSchema.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,KAAKA,OAAO,MAAM,kBAAkB;AAC3C,SAASC,UAAU,EAAEC,SAAS,EAAEC,QAAQ,QAAQ,mBAAmB;AAKnE;;;;;;;;;;;AAWA,OAAO,MAAMC,SAAS,gBAAGJ,OAAO,CAACK,SAAS,CAAU,wCAAwC,EAAE;EAC5FC,YAAY,EAAEL;CACf,CAAC;AAEF;;;;;;;AAOA,OAAO,MAAMM,eAAe,gBAAGP,OAAO,CAACK,SAAS,CAC9C,8CAA8C,EAC9C;EAAEC,YAAY,EAAEL;AAAU,CAAE,CAC7B;AAED;;;;;;;;;;;;;AAaA,OAAO,MAAMO,eAAe,gBAAGR,OAAO,CAACK,SAAS,CAC9C,8CAA8C,EAC9C;EAAEC,YAAY,EAAEL;AAAU,CAAE,CAC7B;AAED;;;;;;;AAOA,OAAO,MAAMQ,0BAA0B,GAAIC,OAA+B,IAAa;EACrF,MAAMC,KAAK,GAAGX,OAAO,CAACY,GAAG,CAACF,OAAO,EAAEF,eAAe,CAAC;EACnD,OAAOG,KAAK,KAAK,IAAI,IAAIA,KAAK,KAAK,QAAQ;AAC7C,CAAC;AAED;;;;;;;AAOA,OAAO,MAAME,0BAA0B,GAAIH,OAA+B,IAAa;EACrF,MAAMC,KAAK,GAAGX,OAAO,CAACY,GAAG,CAACF,OAAO,EAAEF,eAAe,CAAC;EACnD,OAAOG,KAAK,KAAK,IAAI,IAAIA,KAAK,KAAK,QAAQ;AAC7C,CAAC;AAED;;;;;;;;;;AAUA,OAAO,MAAMG,UAAU,gBAAGd,OAAO,CAACK,SAAS,CACzC,yCAAyC,EACzC;EAAEC,YAAY,EAAEA,CAAA,KAAOS,CAAC,IAAK;AAAS,CAAE,CACzC;AAED;;;;;;;;;;;AAWA,OAAO,MAAMC,oBAAoB,gBAAGhB,OAAO,CAACK,SAAS,CAAU,mDAAmD,EAAE;EAClHC,YAAY,EAAEJ;CACf,CAAC;AAEF;;;;;;;AAOA,OAAO,MAAMe,OAAO,gBAAGjB,OAAO,CAACK,SAAS,CAGtC,sCAAsC,EACtC;EAAEC,YAAY,EAAEA,CAAA,KAAMH;AAAQ,CAAE,CACjC","ignoreList":[]}
+{"version":3,"file":"ClusterSchema.js","names":["Context","constFalse","constTrue","identity","Persisted","Reference","defaultValue","WithTransaction","Uninterruptible","isUninterruptibleForServer","context","value","get","isUninterruptibleForClient","ShardGroup","_","ClientTracingEnabled","Dynamic"],"sources":["../../../src/unstable/cluster/ClusterSchema.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,OAAO,KAAKA,OAAO,MAAM,kBAAkB;AAC3C,SAASC,UAAU,EAAEC,SAAS,EAAEC,QAAQ,QAAQ,mBAAmB;AAKnE;;;;;;;;;;;AAWA,OAAO,MAAMC,SAAS,gBAAGJ,OAAO,CAACK,SAAS,CAAU,wCAAwC,EAAE;EAC5FC,YAAY,EAAEL;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMM,eAAe,gBAAGP,OAAO,CAACK,SAAS,CAC9C,8CAA8C,EAC9C;EAAEC,YAAY,EAAEL;AAAU,CAAE,CAC7B;AAED;;;;;;;;;;;;;AAaA,OAAO,MAAMO,eAAe,gBAAGR,OAAO,CAACK,SAAS,CAC9C,8CAA8C,EAC9C;EAAEC,YAAY,EAAEL;AAAU,CAAE,CAC7B;AAED;;;;;;;;;;;;;;AAcA,OAAO,MAAMQ,0BAA0B,GAAIC,OAA+B,IAAa;EACrF,MAAMC,KAAK,GAAGX,OAAO,CAACY,GAAG,CAACF,OAAO,EAAEF,eAAe,CAAC;EACnD,OAAOG,KAAK,KAAK,IAAI,IAAIA,KAAK,KAAK,QAAQ;AAC7C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAME,0BAA0B,GAAIH,OAA+B,IAAa;EACrF,MAAMC,KAAK,GAAGX,OAAO,CAACY,GAAG,CAACF,OAAO,EAAEF,eAAe,CAAC;EACnD,OAAOG,KAAK,KAAK,IAAI,IAAIA,KAAK,KAAK,QAAQ;AAC7C,CAAC;AAED;;;;;;;;;;AAUA,OAAO,MAAMG,UAAU,gBAAGd,OAAO,CAACK,SAAS,CACzC,yCAAyC,EACzC;EAAEC,YAAY,EAAEA,CAAA,KAAOS,CAAC,IAAK;AAAS,CAAE,CACzC;AAED;;;;;;;;;;;AAWA,OAAO,MAAMC,oBAAoB,gBAAGhB,OAAO,CAACK,SAAS,CAAU,mDAAmD,EAAE;EAClHC,YAAY,EAAEJ;CACf,CAAC;AAEF;;;;;;;AAOA,OAAO,MAAMe,OAAO,gBAAGjB,OAAO,CAACK,SAAS,CAGtC,sCAAsC,EACtC;EAAEC,YAAY,EAAEA,CAAA,KAAMH;AAAQ,CAAE,CACjC","ignoreList":[]}

package/dist/unstable/cluster/Entity.d.ts

@@ -162,6 +162,23 @@ protocol: RpcGroup.RpcGroup<Rpcs>) => Entity<Type, Rpcs>;
  * Creates a new `Entity` of the specified `type` which will accept messages
  * that adhere to the provided schemas.
  *
+ * **When to use**
+ *
+ * Use to define a cluster entity from individual `Rpc` definitions, giving the
+ * cluster runtime a typed protocol for handlers and per-entity clients.
+ *
+ * **Details**
+ *
+ * The `type` argument is stored as the entity `EntityType`, and the RPC array
+ * is grouped into the entity's `protocol`.
+ *
+ * **Gotchas**
+ *
+ * RPC tags should be unique within the array. If multiple definitions use the
+ * same tag, the resulting protocol keeps the later definition for that tag.
+ *
+ * @see {@link fromRpcGroup} for creating an entity from an existing `RpcGroup`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -198,7 +215,7 @@ export declare class CurrentRunnerAddress extends CurrentRunnerAddress_base {
  *
  * **When to use**
  *
- * Use it to complete an entity request by succeeding, failing, failing with a
+ * Use when you use it to complete an entity request by succeeding, failing, failing with a
  * cause, or supplying an explicit `Exit`.
  *
  * @category Replier