effect 4.0.0-beta.66 → 4.0.0-beta.68

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

@@ -1,30 +1,64 @@
 /**
+ * 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 declare const entities: Metric.Gauge<bigint>;
 /**
- * @since 4.0.0
+ * Gauge tracking the number of singleton processes currently running on the
+ * current runner.
+ *
  * @category metrics
+ * @since 4.0.0
  */
 export declare const singletons: Metric.Gauge<bigint>;
 /**
- * @since 4.0.0
+ * Gauge tracking the number of registered cluster runners.
+ *
  * @category metrics
+ * @since 4.0.0
  */
 export declare const runners: Metric.Gauge<bigint>;
 /**
- * @since 4.0.0
+ * Gauge tracking the number of cluster runners currently considered healthy.
+ *
  * @category metrics
+ * @since 4.0.0
  */
 export declare const runnersHealthy: Metric.Gauge<bigint>;
 /**
- * @since 4.0.0
+ * Gauge tracking the number of shards currently acquired by the current runner.
+ *
  * @category metrics
+ * @since 4.0.0
  */
 export declare const shards: Metric.Gauge<bigint>;
 //# sourceMappingURL=ClusterMetrics.d.ts.map

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;;GAEG;AACH,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC;;;GAGG;AACH,eAAO,MAAM,QAAQ,sBAA4D,CAAA;AAEjF;;;GAGG;AACH,eAAO,MAAM,UAAU,sBAA8D,CAAA;AAErF;;;GAGG;AACH,eAAO,MAAM,OAAO,sBAA2D,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,cAAc,sBAAmE,CAAA;AAE9F;;;GAGG;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;;;;;;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"}

package/dist/unstable/cluster/ClusterMetrics.js

@@ -1,38 +1,72 @@
 /**
+ * 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.js";
 /**
- * @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 = /*#__PURE__*/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 = /*#__PURE__*/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 = /*#__PURE__*/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 = /*#__PURE__*/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 = /*#__PURE__*/Metric.gauge("effect_cluster_shards", {
   bigint: true

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;;;AAGA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AAEzC;;;;AAIA,OAAO,MAAMC,QAAQ,gBAAGD,MAAM,CAACE,KAAK,CAAC,yBAAyB,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAEjF;;;;AAIA,OAAO,MAAMC,UAAU,gBAAGJ,MAAM,CAACE,KAAK,CAAC,2BAA2B,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAErF;;;;AAIA,OAAO,MAAME,OAAO,gBAAGL,MAAM,CAACE,KAAK,CAAC,wBAAwB,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAE/E;;;;AAIA,OAAO,MAAMG,cAAc,gBAAGN,MAAM,CAACE,KAAK,CAAC,gCAAgC,EAAE;EAAEC,MAAM,EAAE;AAAI,CAAE,CAAC;AAE9F;;;;AAIA,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;;;;;;;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":[]}

package/dist/unstable/cluster/ClusterSchema.d.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";
@@ -6,49 +32,76 @@ import type * as Rpc from "../rpc/Rpc.ts";
 import type { EntityId } from "./EntityId.ts";
 import type { Request } from "./Envelope.ts";
 /**
+ * Annotation that marks whether a cluster request should be persisted in mailbox
+ * storage.
+ *
+ * The default value is `false`.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export declare const Persisted: Context.Reference<boolean>;
 /**
  * Whether to wrap the request with a storage transaction, so sql queries are
  * committed atomically.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export declare const WithTransaction: Context.Reference<boolean>;
 /**
+ * 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
- * @category Annotations
  */
 export declare const Uninterruptible: Context.Reference<boolean | "server" | "client">;
 /**
+ * Returns whether the `Uninterruptible` annotation applies to server-side
+ * request handling for the provided context.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export declare const isUninterruptibleForServer: (context: Context.Context<never>) => boolean;
 /**
+ * Returns whether the `Uninterruptible` annotation applies to client-side
+ * request handling for the provided context.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export declare const isUninterruptibleForClient: (context: Context.Context<never>) => boolean;
 /**
+ * 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
- * @category Annotations
  */
 export declare const ShardGroup: Context.Reference<(entityId: EntityId) => string>;
 /**
+ * Annotation that controls whether client-side cluster request tracing is
+ * enabled.
+ *
+ * The default value is `true`.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export declare const ClientTracingEnabled: Context.Reference<boolean>;
 /**
  * Dynamically transform the request annotations based on the request.
  * This only applies to the requests handled by the Entity, not the client.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export declare const Dynamic: Context.Reference<(annotations: Context.Context<never>, request: Request<Rpc.AnyWithProps>) => Context.Context<never>>;
 //# sourceMappingURL=ClusterSchema.d.ts.map

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;;GAEG;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;;;GAGG;AACH,eAAO,MAAM,SAAS,4BAEpB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,4BAG3B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,kDAG3B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,OAG5E,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,OAG5E,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,+BAAgC,QAAQ,KAAK,MAAM,CAGzE,CAAA;AAED;;;GAGG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,4BAEpB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,4BAG3B,CAAA;AAED;;;;;;;;;;GAUG;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;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,+BAAgC,QAAQ,KAAK,MAAM,CAGzE,CAAA;AAED;;;;;;;;GAQG;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,11 +1,42 @@
 /**
+ * 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.js";
 import { constFalse, constTrue, identity } from "../../Function.js";
 /**
+ * Annotation that marks whether a cluster request should be persisted in mailbox
+ * storage.
+ *
+ * The default value is `false`.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const Persisted = /*#__PURE__*/Context.Reference("effect/cluster/ClusterSchema/Persisted", {
   defaultValue: constFalse
@@ -14,45 +45,67 @@ export const Persisted = /*#__PURE__*/Context.Reference("effect/cluster/ClusterS
  * Whether to wrap the request with a storage transaction, so sql queries are
  * committed atomically.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const WithTransaction = /*#__PURE__*/Context.Reference("effect/cluster/ClusterSchema/WithTransaction", {
   defaultValue: constFalse
 });
 /**
+ * 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
- * @category Annotations
  */
 export const Uninterruptible = /*#__PURE__*/Context.Reference("effect/cluster/ClusterSchema/Uninterruptible", {
   defaultValue: constFalse
 });
 /**
+ * Returns whether the `Uninterruptible` annotation applies to server-side
+ * request handling for the provided context.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const isUninterruptibleForServer = context => {
   const value = Context.get(context, Uninterruptible);
   return value === true || value === "server";
 };
 /**
+ * Returns whether the `Uninterruptible` annotation applies to client-side
+ * request handling for the provided context.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const isUninterruptibleForClient = context => {
   const value = Context.get(context, Uninterruptible);
   return value === true || value === "client";
 };
 /**
+ * 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
- * @category Annotations
  */
 export const ShardGroup = /*#__PURE__*/Context.Reference("effect/cluster/ClusterSchema/ShardGroup", {
   defaultValue: () => _ => "default"
 });
 /**
+ * Annotation that controls whether client-side cluster request tracing is
+ * enabled.
+ *
+ * The default value is `true`.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const ClientTracingEnabled = /*#__PURE__*/Context.Reference("effect/cluster/ClusterSchema/ClientTracingEnabled", {
   defaultValue: constTrue
@@ -61,8 +114,8 @@ export const ClientTracingEnabled = /*#__PURE__*/Context.Reference("effect/clust
  * Dynamically transform the request annotations based on the request.
  * This only applies to the requests handled by the Entity, not the client.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const Dynamic = /*#__PURE__*/Context.Reference("effect/cluster/ClusterSchema/Dynamic", {
   defaultValue: () => identity

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;;;AAGA,OAAO,KAAKA,OAAO,MAAM,kBAAkB;AAC3C,SAASC,UAAU,EAAEC,SAAS,EAAEC,QAAQ,QAAQ,mBAAmB;AAKnE;;;;AAIA,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;;;;AAIA,OAAO,MAAMO,eAAe,gBAAGR,OAAO,CAACK,SAAS,CAC9C,8CAA8C,EAC9C;EAAEC,YAAY,EAAEL;AAAU,CAAE,CAC7B;AAED;;;;AAIA,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;;;;AAIA,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;;;;AAIA,OAAO,MAAMG,UAAU,gBAAGd,OAAO,CAACK,SAAS,CACzC,yCAAyC,EACzC;EAAEC,YAAY,EAAEA,CAAA,KAAOS,CAAC,IAAK;AAAS,CAAE,CACzC;AAED;;;;AAIA,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,KAAKA,OAAO,MAAM,kBAAkB;AAC3C,SAASC,UAAU,EAAEC,SAAS,EAAEC,QAAQ,QAAQ,mBAAmB;AAKnE;;;;;;;;;AASA,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;;;;;;;;;;;AAWA,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;;;;;;;;AAQA,OAAO,MAAMG,UAAU,gBAAGd,OAAO,CAACK,SAAS,CACzC,yCAAyC,EACzC;EAAEC,YAAY,EAAEA,CAAA,KAAOS,CAAC,IAAK;AAAS,CAAE,CACzC;AAED;;;;;;;;;AASA,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/ClusterWorkflowEngine.d.ts

@@ -13,8 +13,14 @@ import * as WorkflowEngine from "../workflow/WorkflowEngine.ts";
 import { MessageStorage } from "./MessageStorage.ts";
 import * as Sharding from "./Sharding.ts";
 /**
+ * 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
- * @category Constructors
  */
 export declare const make: Effect.Effect<{
     readonly register: <Name extends string, Payload extends Workflow.AnyStructSchema, Success extends Schema.Top, Error extends Schema.Top, R>(workflow: Workflow.Workflow<Name, Payload, Success, Error>, execute: (payload: Payload["Type"], executionId: string) => Effect.Effect<Success["Type"], Error["Type"], R>) => Effect.Effect<void, never, Scope.Scope | Exclude<R, WorkflowEngine.WorkflowEngine | WorkflowEngine.WorkflowInstance | Workflow.Execution<Name> | Scope.Scope> | Payload["DecodingServices"] | Payload["EncodingServices"] | Success["DecodingServices"] | Success["EncodingServices"] | Error["DecodingServices"] | Error["EncodingServices"]>;
@@ -42,8 +48,14 @@ export declare const make: Effect.Effect<{
     }) => Effect.Effect<void>;
 }, never, Scope.Scope | MessageStorage | Sharding.Sharding>;
 /**
+ * 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
- * @category Layers
  */
 export declare const layer: Layer.Layer<WorkflowEngine.WorkflowEngine, never, Sharding.Sharding | MessageStorage>;
 //# sourceMappingURL=ClusterWorkflowEngine.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ClusterWorkflowEngine.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ClusterWorkflowEngine.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,IAAI,MAAM,eAAe,CAAA;AAGrC,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAIzC,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAG5C,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAA;AACnD,OAAO,KAAK,YAAY,MAAM,6BAA6B,CAAA;AAC3D,OAAO,KAAK,eAAe,MAAM,gCAAgC,CAAA;AACjE,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAA;AACnD,OAAO,KAAK,cAAc,MAAM,+BAA+B,CAAA;AAS/D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGpD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAGzC;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;wBAiBa,CAAC;uCAIvB,CAAR;;;;;;;;;;;;;;;;;;2DAkfE,CAAA;AAoIF;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAC7B,cAAc,CAAC,cAAc,EAC7B,KAAK,EACL,QAAQ,CAAC,QAAQ,GAAG,cAAc,CAGnC,CAAA"}
+{"version":3,"file":"ClusterWorkflowEngine.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ClusterWorkflowEngine.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,IAAI,MAAM,eAAe,CAAA;AAGrC,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAIzC,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAG5C,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAA;AACnD,OAAO,KAAK,YAAY,MAAM,6BAA6B,CAAA;AAC3D,OAAO,KAAK,eAAe,MAAM,gCAAgC,CAAA;AACjE,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAA;AACnD,OAAO,KAAK,cAAc,MAAM,+BAA+B,CAAA;AAS/D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGpD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAGzC;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI;;;;;wBAoBP,CAAA;uCAEsC,CAAC;;;;;;;;;;;;;;;;;;2DAif/C,CAAA;AAoIF;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAC7B,cAAc,CAAC,cAAc,EAC7B,KAAK,EACL,QAAQ,CAAC,QAAQ,GAAG,cAAc,CAGnC,CAAA"}

package/dist/unstable/cluster/ClusterWorkflowEngine.js

@@ -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.js";
@@ -34,8 +55,14 @@ import * as Reply from "./Reply.js";
 import * as Sharding from "./Sharding.js";
 import * as Snowflake from "./Snowflake.js";
 /**
+ * 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
- * @category Constructors
  */
 export const make = /*#__PURE__*/Effect.gen(function* () {
   const sharding = yield* Sharding.Sharding;
@@ -489,8 +516,14 @@ const ClockEntityLayer = /*#__PURE__*/ClockEntity.toLayer(/*#__PURE__*/Effect.ge
 }));
 const InterruptSignal = /*#__PURE__*/DurableDeferred.make("Workflow/InterruptSignal");
 /**
+ * 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
- * @category Layers
  */
 export const layer = /*#__PURE__*/ClockEntityLayer.pipe(/*#__PURE__*/Layer.provideMerge(/*#__PURE__*/Layer.effect(WorkflowEngine.WorkflowEngine)(make)));
 //# sourceMappingURL=ClusterWorkflowEngine.js.map