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

package/dist/unstable/cluster/Runner.js

@@ -1,4 +1,28 @@
 /**
+ * The `Runner` module defines the membership record used by the unstable
+ * cluster runtime to describe a process that can host entity shards.
+ *
+ * A runner combines the network address used by other runners to reach it, the
+ * shard groups it participates in, and a relative weight used when the sharding
+ * service assigns shards across the healthy runners in each group.
+ *
+ * **Common tasks**
+ *
+ * - Construct the runner registered by the local `Sharding` layer
+ * - Persist or exchange runner metadata through `RunnerStorage`
+ * - Encode and decode runner values at cluster transport or storage boundaries
+ * - Tune shard distribution by adjusting the runner's group membership and
+ *   relative weight
+ *
+ * **Gotchas**
+ *
+ * - Runner addresses must be stable and unique while a runner is registered,
+ *   because they identify the owner used for routing and shard locks.
+ * - Weights are relative within each shard group; changing weights or groups can
+ *   rebalance shard ownership as the cluster refreshes its runner view.
+ * - Runner equality and hashing are based on address and weight, so compare
+ *   `groups` explicitly when group membership is the important distinction.
+ *
  * @since 4.0.0
  */
 import * as Equal from "../../Equal.js";
@@ -8,17 +32,13 @@ import * as Schema from "../../Schema.js";
 import { RunnerAddress } from "./RunnerAddress.js";
 const TypeId = "~effect/cluster/Runner";
 /**
- * A `Runner` represents a physical application server that is capable of running
- * entities.
- *
- * Because a Runner represents a physical application server, a Runner must have a
- * unique `address` which can be used to communicate with the server.
+ * A cluster runner that can host entities.
  *
- * The version of a Runner is used during rebalancing to give priority to newer
- * application servers and slowly decommission older ones.
+ * Each runner has a unique network `address`, the shard `groups` it participates
+ * in, and a relative `weight` used when assigning shards across runners.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class Runner extends /*#__PURE__*/Schema.Class(TypeId)({
   address: RunnerAddress,
@@ -26,40 +46,56 @@ export class Runner extends /*#__PURE__*/Schema.Class(TypeId)({
   weight: Schema.Number
 }) {
   /**
+   * Formatter for rendering runner values consistently.
+   *
    * @since 4.0.0
    */
   static format = /*#__PURE__*/Schema.toFormatter(this);
   /**
+   * Marks this value as a cluster runner for runtime guards.
+   *
    * @since 4.0.0
    */
   [TypeId] = TypeId;
   /**
+   * Decodes a runner from its JSON string representation.
+   *
    * @since 4.0.0
    */
   static decodeSync = /*#__PURE__*/Schema.decodeSync(/*#__PURE__*/Schema.fromJsonString(Runner));
   /**
+   * Encodes a runner to its JSON string representation.
+   *
    * @since 4.0.0
    */
   static encodeSync = /*#__PURE__*/Schema.encodeSync(/*#__PURE__*/Schema.fromJsonString(Runner));
   /**
+   * Formats this runner as a string.
+   *
    * @since 4.0.0
    */
   toString() {
     return Runner.format(this);
   }
   /**
+   * Formats this runner for Node.js inspection.
+   *
    * @since 4.0.0
    */
   [NodeInspectSymbol]() {
     return this.toString();
   }
   /**
+   * Compares runners by address and shard-assignment weight.
+   *
    * @since 4.0.0
    */
   [Equal.symbol](that) {
     return this.address[Equal.symbol](that.address) && this.weight === that.weight;
   }
   /**
+   * Computes a structural hash from the runner address and shard-assignment weight.
+   *
    * @since 4.0.0
    */
   [Hash.symbol]() {
@@ -67,17 +103,11 @@ export class Runner extends /*#__PURE__*/Schema.Class(TypeId)({
   }
 }
 /**
- * A `Runner` represents a physical application server that is capable of running
- * entities.
- *
- * Because a Runner represents a physical application server, a Runner must have a
- * unique `address` which can be used to communicate with the server.
+ * Constructs a `Runner` from its network address, shard groups, and relative
+ * shard-assignment weight.
  *
- * The version of a Runner is used during rebalancing to give priority to newer
- * application servers and slowly decommission older ones.
- *
- * @since 4.0.0
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = props => new Runner(props, {
   disableChecks: true

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

@@ -1 +1 @@
-{"version":3,"file":"Runner.js","names":["Equal","Hash","NodeInspectSymbol","Schema","RunnerAddress","TypeId","Runner","Class","address","groups","Array","String","weight","Number","format","toFormatter","decodeSync","fromJsonString","encodeSync","toString","symbol","that","string","make","props","disableChecks"],"sources":["../../../src/unstable/cluster/Runner.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAGA,OAAO,KAAKA,KAAK,MAAM,gBAAgB;AACvC,OAAO,KAAKC,IAAI,MAAM,eAAe;AACrC,SAASC,iBAAiB,QAAQ,sBAAsB;AACxD,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AACzC,SAASC,aAAa,QAAQ,oBAAoB;AAElD,MAAMC,MAAM,GAAG,wBAAwB;AAEvC;;;;;;;;;;;;;AAaA,OAAM,MAAOC,MAAO,sBAAQH,MAAM,CAACI,KAAK,CAASF,MAAM,CAAC,CAAC;EACvDG,OAAO,EAAEJ,aAAa;EACtBK,MAAM,eAAEN,MAAM,CAACO,KAAK,CAACP,MAAM,CAACQ,MAAM,CAAC;EACnCC,MAAM,EAAET,MAAM,CAACU;CAChB,CAAC;EACA;;;EAGA,OAAOC,MAAM,gBAAGX,MAAM,CAACY,WAAW,CAAC,IAAI,CAAC;EAExC;;;EAGS,CAACV,MAAM,IAAIA,MAAM;EAE1B;;;EAGA,OAAgBW,UAAU,gBAAGb,MAAM,CAACa,UAAU,cAACb,MAAM,CAACc,cAAc,CAACX,MAAM,CAAC,CAAC;EAE7E;;;EAGA,OAAgBY,UAAU,gBAAGf,MAAM,CAACe,UAAU,cAACf,MAAM,CAACc,cAAc,CAACX,MAAM,CAAC,CAAC;EAE7E;;;EAGSa,QAAQA,CAAA;IACf,OAAOb,MAAM,CAACQ,MAAM,CAAC,IAAI,CAAC;EAC5B;EAEA;;;EAGA,CAACZ,iBAAiB,IAAC;IACjB,OAAO,IAAI,CAACiB,QAAQ,EAAE;EACxB;EAEA;;;EAGA,CAACnB,KAAK,CAACoB,MAAM,EAAEC,IAAY;IACzB,OAAO,IAAI,CAACb,OAAO,CAACR,KAAK,CAACoB,MAAM,CAAC,CAACC,IAAI,CAACb,OAAO,CAAC,IAAI,IAAI,CAACI,MAAM,KAAKS,IAAI,CAACT,MAAM;EAChF;EAEA;;;EAGA,CAACX,IAAI,CAACmB,MAAM,IAAC;IACX,OAAOnB,IAAI,CAACqB,MAAM,CAAC,GAAG,IAAI,CAACd,OAAO,CAACW,QAAQ,EAAE,IAAI,IAAI,CAACP,MAAM,EAAE,CAAC;EACjE;;AAGF;;;;;;;;;;;;;AAaA,OAAO,MAAMW,IAAI,GAAIC,KAIpB,IAAa,IAAIlB,MAAM,CAACkB,KAAK,EAAE;EAAEC,aAAa,EAAE;AAAI,CAAE,CAAC","ignoreList":[]}
+{"version":3,"file":"Runner.js","names":["Equal","Hash","NodeInspectSymbol","Schema","RunnerAddress","TypeId","Runner","Class","address","groups","Array","String","weight","Number","format","toFormatter","decodeSync","fromJsonString","encodeSync","toString","symbol","that","string","make","props","disableChecks"],"sources":["../../../src/unstable/cluster/Runner.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,KAAKA,KAAK,MAAM,gBAAgB;AACvC,OAAO,KAAKC,IAAI,MAAM,eAAe;AACrC,SAASC,iBAAiB,QAAQ,sBAAsB;AACxD,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AACzC,SAASC,aAAa,QAAQ,oBAAoB;AAElD,MAAMC,MAAM,GAAG,wBAAwB;AAEvC;;;;;;;;;AASA,OAAM,MAAOC,MAAO,sBAAQH,MAAM,CAACI,KAAK,CAASF,MAAM,CAAC,CAAC;EACvDG,OAAO,EAAEJ,aAAa;EACtBK,MAAM,eAAEN,MAAM,CAACO,KAAK,CAACP,MAAM,CAACQ,MAAM,CAAC;EACnCC,MAAM,EAAET,MAAM,CAACU;CAChB,CAAC;EACA;;;;;EAKA,OAAOC,MAAM,gBAAGX,MAAM,CAACY,WAAW,CAAC,IAAI,CAAC;EAExC;;;;;EAKS,CAACV,MAAM,IAAIA,MAAM;EAE1B;;;;;EAKA,OAAgBW,UAAU,gBAAGb,MAAM,CAACa,UAAU,cAACb,MAAM,CAACc,cAAc,CAACX,MAAM,CAAC,CAAC;EAE7E;;;;;EAKA,OAAgBY,UAAU,gBAAGf,MAAM,CAACe,UAAU,cAACf,MAAM,CAACc,cAAc,CAACX,MAAM,CAAC,CAAC;EAE7E;;;;;EAKSa,QAAQA,CAAA;IACf,OAAOb,MAAM,CAACQ,MAAM,CAAC,IAAI,CAAC;EAC5B;EAEA;;;;;EAKA,CAACZ,iBAAiB,IAAC;IACjB,OAAO,IAAI,CAACiB,QAAQ,EAAE;EACxB;EAEA;;;;;EAKA,CAACnB,KAAK,CAACoB,MAAM,EAAEC,IAAY;IACzB,OAAO,IAAI,CAACb,OAAO,CAACR,KAAK,CAACoB,MAAM,CAAC,CAACC,IAAI,CAACb,OAAO,CAAC,IAAI,IAAI,CAACI,MAAM,KAAKS,IAAI,CAACT,MAAM;EAChF;EAEA;;;;;EAKA,CAACX,IAAI,CAACmB,MAAM,IAAC;IACX,OAAOnB,IAAI,CAACqB,MAAM,CAAC,GAAG,IAAI,CAACd,OAAO,CAACW,QAAQ,EAAE,IAAI,IAAI,CAACP,MAAM,EAAE,CAAC;EACjE;;AAGF;;;;;;;AAOA,OAAO,MAAMW,IAAI,GAAIC,KAIpB,IAAa,IAAIlB,MAAM,CAACkB,KAAK,EAAE;EAAEC,aAAa,EAAE;AAAI,CAAE,CAAC","ignoreList":[]}

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

@@ -1,4 +1,20 @@
 /**
+ * The `RunnerAddress` module defines the network identity used to locate a
+ * cluster runner. A runner address is a host and port pair that can be encoded,
+ * compared, hashed, inspected, and used as a stable primary key.
+ *
+ * **Common use cases**
+ *
+ * - Representing the target runner for cluster routing and placement decisions
+ * - Persisting or exchanging runner endpoints through schemas
+ * - Using runner endpoints as keys in maps, registries, or shard ownership data
+ *
+ * **Gotchas**
+ *
+ * - Identity is structural: two addresses are equal when both host and port match
+ * - The primary key is formatted as `host:port`, so host strings should already
+ *   be normalized for the routing layer using them
+ *
  * @since 4.0.0
  */
 import * as Equal from "../../Equal.ts";
@@ -12,38 +28,54 @@ declare const RunnerAddress_base: Schema.Class<RunnerAddress, Schema.Struct<{
     readonly port: Schema.Number;
 }>, {}>;
 /**
- * @since 4.0.0
+ * Network address of a cluster runner, identified by host and port.
+ *
  * @category models
+ * @since 4.0.0
  */
 export declare class RunnerAddress extends RunnerAddress_base {
     /**
+     * Marks this value as a cluster runner address for runtime guards.
+     *
      * @since 4.0.0
      */
     readonly [TypeId] = "~effect/cluster/RunnerAddress";
     /**
+     * Compares runner addresses by host and port.
+     *
      * @since 4.0.0
      */
     [Equal.symbol](that: RunnerAddress): boolean;
     /**
+     * Computes a structural hash from the host and port.
+     *
      * @since 4.0.0
      */
     [Hash.symbol](): number;
     /**
+     * Stable primary key used to identify the runner address.
+     *
      * @since 4.0.0
      */
     [PrimaryKey.symbol](): string;
     /**
+     * Formats the runner address with its host and port.
+     *
      * @since 4.0.0
      */
     toString(): string;
     /**
+     * Formats the runner address for Node.js inspection.
+     *
      * @since 4.0.0
      */
     [NodeInspectSymbol](): string;
 }
 /**
- * @since 4.0.0
+ * Constructs a `RunnerAddress` from a host and port.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: (host: string, port: number) => RunnerAddress;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"RunnerAddress.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/RunnerAddress.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,eAAe,CAAA;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,UAAU,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC,QAAA,MAAM,MAAM,kCAAkC,CAAA;;;;;AAE9C;;;GAGG;AACH,qBAAa,aAAc,SAAQ,kBAGjC;IACA;;OAEG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,mCAAU;IAE3B;;OAEG;IACH,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO;IAI5C;;OAEG;IACH,CAAC,IAAI,CAAC,MAAM,CAAC;IAIb;;OAEG;IACH,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,MAAM;IAI7B;;OAEG;IACM,QAAQ,IAAI,MAAM;IAI3B;;OAEG;IACH,CAAC,iBAAiB,CAAC,IAAI,MAAM;CAG9B;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,aACU,CAAA"}
+{"version":3,"file":"RunnerAddress.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/RunnerAddress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,eAAe,CAAA;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,UAAU,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC,QAAA,MAAM,MAAM,kCAAkC,CAAA;;;;;AAE9C;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,kBAGjC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,mCAAU;IAE3B;;;;OAIG;IACH,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO;IAI5C;;;;OAIG;IACH,CAAC,IAAI,CAAC,MAAM,CAAC;IAIb;;;;OAIG;IACH,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,MAAM;IAI7B;;;;OAIG;IACM,QAAQ,IAAI,MAAM;IAI3B;;;;OAIG;IACH,CAAC,iBAAiB,CAAC,IAAI,MAAM;CAG9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,aACU,CAAA"}

package/dist/unstable/cluster/RunnerAddress.js

@@ -1,4 +1,20 @@
 /**
+ * The `RunnerAddress` module defines the network identity used to locate a
+ * cluster runner. A runner address is a host and port pair that can be encoded,
+ * compared, hashed, inspected, and used as a stable primary key.
+ *
+ * **Common use cases**
+ *
+ * - Representing the target runner for cluster routing and placement decisions
+ * - Persisting or exchanging runner endpoints through schemas
+ * - Using runner endpoints as keys in maps, registries, or shard ownership data
+ *
+ * **Gotchas**
+ *
+ * - Identity is structural: two addresses are equal when both host and port match
+ * - The primary key is formatted as `host:port`, so host strings should already
+ *   be normalized for the routing layer using them
+ *
  * @since 4.0.0
  */
 import * as Equal from "../../Equal.js";
@@ -8,42 +24,56 @@ import * as PrimaryKey from "../../PrimaryKey.js";
 import * as Schema from "../../Schema.js";
 const TypeId = "~effect/cluster/RunnerAddress";
 /**
- * @since 4.0.0
+ * Network address of a cluster runner, identified by host and port.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class RunnerAddress extends /*#__PURE__*/Schema.Class(TypeId)({
   host: Schema.String,
   port: Schema.Number
 }) {
   /**
+   * Marks this value as a cluster runner address for runtime guards.
+   *
    * @since 4.0.0
    */
   [TypeId] = TypeId;
   /**
+   * Compares runner addresses by host and port.
+   *
    * @since 4.0.0
    */
   [Equal.symbol](that) {
     return this.host === that.host && this.port === that.port;
   }
   /**
+   * Computes a structural hash from the host and port.
+   *
    * @since 4.0.0
    */
   [Hash.symbol]() {
     return Hash.string(`${this.host}:${this.port}`);
   }
   /**
+   * Stable primary key used to identify the runner address.
+   *
    * @since 4.0.0
    */
   [PrimaryKey.symbol]() {
     return `${this.host}:${this.port}`;
   }
   /**
+   * Formats the runner address with its host and port.
+   *
    * @since 4.0.0
    */
   toString() {
     return `RunnerAddress(${this.host}:${this.port})`;
   }
   /**
+   * Formats the runner address for Node.js inspection.
+   *
    * @since 4.0.0
    */
   [NodeInspectSymbol]() {
@@ -51,8 +81,10 @@ export class RunnerAddress extends /*#__PURE__*/Schema.Class(TypeId)({
   }
 }
 /**
- * @since 4.0.0
+ * Constructs a `RunnerAddress` from a host and port.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (host, port) => new RunnerAddress({
   host,

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

@@ -1 +1 @@
-{"version":3,"file":"RunnerAddress.js","names":["Equal","Hash","NodeInspectSymbol","PrimaryKey","Schema","TypeId","RunnerAddress","Class","host","String","port","Number","symbol","that","string","toString","make","disableChecks"],"sources":["../../../src/unstable/cluster/RunnerAddress.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAGA,OAAO,KAAKA,KAAK,MAAM,gBAAgB;AACvC,OAAO,KAAKC,IAAI,MAAM,eAAe;AACrC,SAASC,iBAAiB,QAAQ,sBAAsB;AACxD,OAAO,KAAKC,UAAU,MAAM,qBAAqB;AACjD,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AAEzC,MAAMC,MAAM,GAAG,+BAA+B;AAE9C;;;;AAIA,OAAM,MAAOC,aAAc,sBAAQF,MAAM,CAACG,KAAK,CAAgBF,MAAM,CAAC,CAAC;EACrEG,IAAI,EAAEJ,MAAM,CAACK,MAAM;EACnBC,IAAI,EAAEN,MAAM,CAACO;CACd,CAAC;EACA;;;EAGS,CAACN,MAAM,IAAIA,MAAM;EAE1B;;;EAGA,CAACL,KAAK,CAACY,MAAM,EAAEC,IAAmB;IAChC,OAAO,IAAI,CAACL,IAAI,KAAKK,IAAI,CAACL,IAAI,IAAI,IAAI,CAACE,IAAI,KAAKG,IAAI,CAACH,IAAI;EAC3D;EAEA;;;EAGA,CAACT,IAAI,CAACW,MAAM,IAAC;IACX,OAAOX,IAAI,CAACa,MAAM,CAAC,GAAG,IAAI,CAACN,IAAI,IAAI,IAAI,CAACE,IAAI,EAAE,CAAC;EACjD;EAEA;;;EAGA,CAACP,UAAU,CAACS,MAAM,IAAC;IACjB,OAAO,GAAG,IAAI,CAACJ,IAAI,IAAI,IAAI,CAACE,IAAI,EAAE;EACpC;EAEA;;;EAGSK,QAAQA,CAAA;IACf,OAAO,iBAAiB,IAAI,CAACP,IAAI,IAAI,IAAI,CAACE,IAAI,GAAG;EACnD;EAEA;;;EAGA,CAACR,iBAAiB,IAAC;IACjB,OAAO,IAAI,CAACa,QAAQ,EAAE;EACxB;;AAGF;;;;AAIA,OAAO,MAAMC,IAAI,GAAGA,CAACR,IAAY,EAAEE,IAAY,KAC7C,IAAIJ,aAAa,CAAC;EAAEE,IAAI;EAAEE;AAAI,CAAE,EAAE;EAAEO,aAAa,EAAE;AAAI,CAAE,CAAC","ignoreList":[]}
+{"version":3,"file":"RunnerAddress.js","names":["Equal","Hash","NodeInspectSymbol","PrimaryKey","Schema","TypeId","RunnerAddress","Class","host","String","port","Number","symbol","that","string","toString","make","disableChecks"],"sources":["../../../src/unstable/cluster/RunnerAddress.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,KAAKA,KAAK,MAAM,gBAAgB;AACvC,OAAO,KAAKC,IAAI,MAAM,eAAe;AACrC,SAASC,iBAAiB,QAAQ,sBAAsB;AACxD,OAAO,KAAKC,UAAU,MAAM,qBAAqB;AACjD,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AAEzC,MAAMC,MAAM,GAAG,+BAA+B;AAE9C;;;;;;AAMA,OAAM,MAAOC,aAAc,sBAAQF,MAAM,CAACG,KAAK,CAAgBF,MAAM,CAAC,CAAC;EACrEG,IAAI,EAAEJ,MAAM,CAACK,MAAM;EACnBC,IAAI,EAAEN,MAAM,CAACO;CACd,CAAC;EACA;;;;;EAKS,CAACN,MAAM,IAAIA,MAAM;EAE1B;;;;;EAKA,CAACL,KAAK,CAACY,MAAM,EAAEC,IAAmB;IAChC,OAAO,IAAI,CAACL,IAAI,KAAKK,IAAI,CAACL,IAAI,IAAI,IAAI,CAACE,IAAI,KAAKG,IAAI,CAACH,IAAI;EAC3D;EAEA;;;;;EAKA,CAACT,IAAI,CAACW,MAAM,IAAC;IACX,OAAOX,IAAI,CAACa,MAAM,CAAC,GAAG,IAAI,CAACN,IAAI,IAAI,IAAI,CAACE,IAAI,EAAE,CAAC;EACjD;EAEA;;;;;EAKA,CAACP,UAAU,CAACS,MAAM,IAAC;IACjB,OAAO,GAAG,IAAI,CAACJ,IAAI,IAAI,IAAI,CAACE,IAAI,EAAE;EACpC;EAEA;;;;;EAKSK,QAAQA,CAAA;IACf,OAAO,iBAAiB,IAAI,CAACP,IAAI,IAAI,IAAI,CAACE,IAAI,GAAG;EACnD;EAEA;;;;;EAKA,CAACR,iBAAiB,IAAC;IACjB,OAAO,IAAI,CAACa,QAAQ,EAAE;EACxB;;AAGF;;;;;;AAMA,OAAO,MAAMC,IAAI,GAAGA,CAACR,IAAY,EAAEE,IAAY,KAC7C,IAAIJ,aAAa,CAAC;EAAEE,IAAI;EAAEE;AAAI,CAAE,EAAE;EAAEO,aAAa,EAAE;AAAI,CAAE,CAAC","ignoreList":[]}

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

@@ -1,4 +1,24 @@
 /**
+ * The `RunnerHealth` module defines the health-check service used by cluster
+ * sharding to decide whether a runner may still own its assigned shards. A
+ * runner that is reported as alive is allowed to keep processing messages,
+ * while a runner that is reported as unavailable can have its shards moved to
+ * another runner.
+ *
+ * **Common tasks**
+ *
+ * - Provide a custom {@link RunnerHealth} service for a cluster deployment
+ * - Use {@link layerPing} to check runners through the cluster runner protocol
+ * - Use {@link layerK8s} when Kubernetes pod readiness should drive health
+ * - Use {@link layerNoop} in tests or environments where runners are always considered healthy
+ *
+ * **Gotchas**
+ *
+ * - Health checks affect shard reassignment, so false negatives can move shards
+ *   away from runners that may still be processing messages
+ * - The Kubernetes implementation treats API failures as healthy to avoid
+ *   reassignment caused by a temporary control-plane outage
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts";
@@ -18,8 +38,8 @@ declare const RunnerHealth_base: Context.ServiceClass<RunnerHealth, "effect/clus
  * still be processing messages. If a Runner is not responsive, then its
  * associated shards can and will be re-assigned to a different Runner.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export declare class RunnerHealth extends RunnerHealth_base {
 }
@@ -28,25 +48,34 @@ export declare class RunnerHealth extends RunnerHealth_base {
  *
  * This is useful for testing.
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export declare const layerNoop: Layer.Layer<RunnerHealth, never, never>;
 /**
- * @since 4.0.0
+ * Creates a `RunnerHealth` service that pings runners through `Runners`, retrying
+ * failed pings on a short schedule and treating a successful ping within the
+ * timeout as healthy.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export declare const makePing: Effect.Effect<RunnerHealth["Service"], never, Runners.Runners | Scope.Scope>;
 /**
  * A layer which will ping a Runner directly to check if it is healthy.
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export declare const layerPing: Layer.Layer<RunnerHealth, never, Runners.Runners>;
 /**
- * @since 4.0.0
+ * Creates a `RunnerHealth` service that checks Kubernetes pod readiness for a
+ * runner host, optionally scoped by namespace and label selector.
+ *
+ * If the Kubernetes API check fails, the runner is treated as healthy.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export declare const makeK8s: (options?: {
     readonly namespace?: string | undefined;
@@ -55,16 +84,15 @@ export declare const makeK8s: (options?: {
     readonly isAlive: (address: RunnerAddress) => Effect.Effect<boolean>;
 }, never, K8s.K8sHttpClient>;
 /**
- * A layer which will check the Kubernetes API to see if a Runner is healthy.
- *
- * The provided HttpClient will need to add the pod's CA certificate to its
- * trusted root certificates in order to communicate with the Kubernetes API.
+ * A layer which checks Kubernetes pod readiness to determine whether a runner is
+ * healthy.
  *
- * The pod service account will also need to have permissions to list pods in
- * order to use this layer.
+ * The provided `HttpClient` must trust the pod CA certificate and the pod service
+ * account must be allowed to list pods. If the Kubernetes API check fails, the
+ * runner is treated as healthy.
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export declare const layerK8s: (options?: {
     readonly namespace?: string | undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"RunnerHealth.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/RunnerHealth.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAEvC,OAAO,KAAK,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;;sBAejB,CAAC,OAAO,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;;AAbxE;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,iBAKA;CAAG;AAErC;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,yCAEpB,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,CAClC,YAAY,CAAC,SAAS,CAAC,EACvB,KAAK,EACL,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAc7B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CACjC,YAAY,EACZ,KAAK,EACL,OAAO,CAAC,OAAO,CACuB,CAAA;AAExC;;;GAGG;AACH,eAAO,MAAM,OAAO;yBACG,MAAM,GAAG,SAAS;6BACd,MAAM,GAAG,SAAS;;sBAzDvB,CAAC,OAAO,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;4BAoEtE,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,GACnB,UAAU;IACR,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5C,GAAG,SAAS,KACZ,KAAK,CAAC,KAAK,CACZ,YAAY,EACZ,KAAK,EACL,GAAG,CAAC,aAAa,CAC8B,CAAA"}
+{"version":3,"file":"RunnerHealth.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/RunnerHealth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAEvC,OAAO,KAAK,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;;sBAejB,CAAC,OAAO,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;;AAbxE;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,iBAKA;CAAG;AAErC;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,yCAEpB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,CAClC,YAAY,CAAC,SAAS,CAAC,EACvB,KAAK,EACL,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAc7B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CACjC,YAAY,EACZ,KAAK,EACL,OAAO,CAAC,OAAO,CACuB,CAAA;AAExC;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO;yBACG,MAAM,GAAG,SAAS;6BACd,MAAM,GAAG,SAAS;;sBAlEvB,CAAC,OAAO,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;4BA6EtE,CAAA;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,GACnB,UAAU;IACR,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5C,GAAG,SAAS,KACZ,KAAK,CAAC,KAAK,CACZ,YAAY,EACZ,KAAK,EACL,GAAG,CAAC,aAAa,CAC8B,CAAA"}

package/dist/unstable/cluster/RunnerHealth.js

@@ -1,4 +1,24 @@
 /**
+ * The `RunnerHealth` module defines the health-check service used by cluster
+ * sharding to decide whether a runner may still own its assigned shards. A
+ * runner that is reported as alive is allowed to keep processing messages,
+ * while a runner that is reported as unavailable can have its shards moved to
+ * another runner.
+ *
+ * **Common tasks**
+ *
+ * - Provide a custom {@link RunnerHealth} service for a cluster deployment
+ * - Use {@link layerPing} to check runners through the cluster runner protocol
+ * - Use {@link layerK8s} when Kubernetes pod readiness should drive health
+ * - Use {@link layerNoop} in tests or environments where runners are always considered healthy
+ *
+ * **Gotchas**
+ *
+ * - Health checks affect shard reassignment, so false negatives can move shards
+ *   away from runners that may still be processing messages
+ * - The Kubernetes implementation treats API failures as healthy to avoid
+ *   reassignment caused by a temporary control-plane outage
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.js";
@@ -14,8 +34,8 @@ import * as Runners from "./Runners.js";
  * still be processing messages. If a Runner is not responsive, then its
  * associated shards can and will be re-assigned to a different Runner.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class RunnerHealth extends /*#__PURE__*/Context.Service()("effect/cluster/RunnerHealth") {}
 /**
@@ -23,15 +43,19 @@ export class RunnerHealth extends /*#__PURE__*/Context.Service()("effect/cluster
  *
  * This is useful for testing.
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerNoop = /*#__PURE__*/Layer.succeed(RunnerHealth, {
   isAlive: () => Effect.succeed(true)
 });
 /**
- * @since 4.0.0
+ * Creates a `RunnerHealth` service that pings runners through `Runners`, retrying
+ * failed pings on a short schedule and treating a successful ping within the
+ * timeout as healthy.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const makePing = /*#__PURE__*/Effect.gen(function* () {
   const runners = yield* Runners.Runners;
@@ -49,13 +73,18 @@ export const makePing = /*#__PURE__*/Effect.gen(function* () {
 /**
  * A layer which will ping a Runner directly to check if it is healthy.
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerPing = /*#__PURE__*/Layer.effect(RunnerHealth, makePing);
 /**
- * @since 4.0.0
+ * Creates a `RunnerHealth` service that checks Kubernetes pod readiness for a
+ * runner host, optionally scoped by namespace and label selector.
+ *
+ * If the Kubernetes API check fails, the runner is treated as healthy.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const makeK8s = /*#__PURE__*/Effect.fnUntraced(function* (options) {
   const allPods = yield* K8s.makeGetPods(options);
@@ -64,16 +93,15 @@ export const makeK8s = /*#__PURE__*/Effect.fnUntraced(function* (options) {
   });
 });
 /**
- * A layer which will check the Kubernetes API to see if a Runner is healthy.
- *
- * The provided HttpClient will need to add the pod's CA certificate to its
- * trusted root certificates in order to communicate with the Kubernetes API.
+ * A layer which checks Kubernetes pod readiness to determine whether a runner is
+ * healthy.
  *
- * The pod service account will also need to have permissions to list pods in
- * order to use this layer.
+ * The provided `HttpClient` must trust the pod CA certificate and the pod service
+ * account must be allowed to list pods. If the Kubernetes API check fails, the
+ * runner is treated as healthy.
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerK8s = options => Layer.effect(RunnerHealth, makeK8s(options));
 //# sourceMappingURL=RunnerHealth.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"RunnerHealth.js","names":["Context","Effect","Layer","Schedule","K8s","Runners","RunnerHealth","Service","layerNoop","succeed","isAlive","makePing","gen","runners","schedule","spaced","address","ping","pipe","timeout","retry","times","isSuccess","of","layerPing","effect","makeK8s","fnUntraced","options","allPods","makeGetPods","map","pods","get","host","isReadyOrInitializing","catchCause","layerK8s"],"sources":["../../../src/unstable/cluster/RunnerHealth.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAGA,OAAO,KAAKA,OAAO,MAAM,kBAAkB;AAC3C,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AACvC,OAAO,KAAKC,QAAQ,MAAM,mBAAmB;AAE7C,OAAO,KAAKC,GAAG,MAAM,oBAAoB;AAEzC,OAAO,KAAKC,OAAO,MAAM,cAAc;AAEvC;;;;;;;;;;AAUA,OAAM,MAAOC,YAAa,sBAAQN,OAAO,CAACO,OAAO,EAK9C,CAAC,6BAA6B,CAAC;AAElC;;;;;;;;AAQA,OAAO,MAAMC,SAAS,gBAAGN,KAAK,CAACO,OAAO,CAACH,YAAY,EAAE;EACnDI,OAAO,EAAEA,CAAA,KAAMT,MAAM,CAACQ,OAAO,CAAC,IAAI;CACnC,CAAC;AAEF;;;;AAIA,OAAO,MAAME,QAAQ,gBAIjBV,MAAM,CAACW,GAAG,CAAC,aAAS;EACtB,MAAMC,OAAO,GAAG,OAAOR,OAAO,CAACA,OAAO;EACtC,MAAMS,QAAQ,GAAGX,QAAQ,CAACY,MAAM,CAAC,GAAG,CAAC;EAErC,SAASL,OAAOA,CAACM,OAAsB;IACrC,OAAOH,OAAO,CAACI,IAAI,CAACD,OAAO,CAAC,CAACE,IAAI,CAC/BjB,MAAM,CAACkB,OAAO,CAAC,MAAM,CAAC,EACtBlB,MAAM,CAACmB,KAAK,CAAC;MAAEC,KAAK,EAAE,CAAC;MAAEP;IAAQ,CAAE,CAAC,EACpCb,MAAM,CAACqB,SAAS,CACjB;EACH;EAEA,OAAOhB,YAAY,CAACiB,EAAE,CAAC;IAAEb;EAAO,CAAE,CAAC;AACrC,CAAC,CAAC;AAEF;;;;;;AAMA,OAAO,MAAMc,SAAS,gBAIlBtB,KAAK,CAACuB,MAAM,CAACnB,YAAY,EAAEK,QAAQ,CAAC;AAExC;;;;AAIA,OAAO,MAAMe,OAAO,gBAAGzB,MAAM,CAAC0B,UAAU,CAAC,WAAUC,OAGlD;EACC,MAAMC,OAAO,GAAG,OAAOzB,GAAG,CAAC0B,WAAW,CAACF,OAAO,CAAC;EAE/C,OAAOtB,YAAY,CAACiB,EAAE,CAAC;IACrBb,OAAO,EAAGM,OAAO,IACfa,OAAO,CAACX,IAAI,CACVjB,MAAM,CAAC8B,GAAG,CAAEC,IAAI,IAAKA,IAAI,CAACC,GAAG,CAACjB,OAAO,CAACkB,IAAI,CAAC,EAAEC,qBAAqB,IAAI,KAAK,CAAC,EAC5ElC,MAAM,CAACmC,UAAU,CAAC,MAAMnC,MAAM,CAACQ,OAAO,CAAC,IAAI,CAAC,CAAC;GAElD,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;;AAYA,OAAO,MAAM4B,QAAQ,GACnBT,OAGa,IAKV1B,KAAK,CAACuB,MAAM,CAACnB,YAAY,EAAEoB,OAAO,CAACE,OAAO,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"RunnerHealth.js","names":["Context","Effect","Layer","Schedule","K8s","Runners","RunnerHealth","Service","layerNoop","succeed","isAlive","makePing","gen","runners","schedule","spaced","address","ping","pipe","timeout","retry","times","isSuccess","of","layerPing","effect","makeK8s","fnUntraced","options","allPods","makeGetPods","map","pods","get","host","isReadyOrInitializing","catchCause","layerK8s"],"sources":["../../../src/unstable/cluster/RunnerHealth.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,KAAKA,OAAO,MAAM,kBAAkB;AAC3C,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AACvC,OAAO,KAAKC,QAAQ,MAAM,mBAAmB;AAE7C,OAAO,KAAKC,GAAG,MAAM,oBAAoB;AAEzC,OAAO,KAAKC,OAAO,MAAM,cAAc;AAEvC;;;;;;;;;;AAUA,OAAM,MAAOC,YAAa,sBAAQN,OAAO,CAACO,OAAO,EAK9C,CAAC,6BAA6B,CAAC;AAElC;;;;;;;;AAQA,OAAO,MAAMC,SAAS,gBAAGN,KAAK,CAACO,OAAO,CAACH,YAAY,EAAE;EACnDI,OAAO,EAAEA,CAAA,KAAMT,MAAM,CAACQ,OAAO,CAAC,IAAI;CACnC,CAAC;AAEF;;;;;;;;AAQA,OAAO,MAAME,QAAQ,gBAIjBV,MAAM,CAACW,GAAG,CAAC,aAAS;EACtB,MAAMC,OAAO,GAAG,OAAOR,OAAO,CAACA,OAAO;EACtC,MAAMS,QAAQ,GAAGX,QAAQ,CAACY,MAAM,CAAC,GAAG,CAAC;EAErC,SAASL,OAAOA,CAACM,OAAsB;IACrC,OAAOH,OAAO,CAACI,IAAI,CAACD,OAAO,CAAC,CAACE,IAAI,CAC/BjB,MAAM,CAACkB,OAAO,CAAC,MAAM,CAAC,EACtBlB,MAAM,CAACmB,KAAK,CAAC;MAAEC,KAAK,EAAE,CAAC;MAAEP;IAAQ,CAAE,CAAC,EACpCb,MAAM,CAACqB,SAAS,CACjB;EACH;EAEA,OAAOhB,YAAY,CAACiB,EAAE,CAAC;IAAEb;EAAO,CAAE,CAAC;AACrC,CAAC,CAAC;AAEF;;;;;;AAMA,OAAO,MAAMc,SAAS,gBAIlBtB,KAAK,CAACuB,MAAM,CAACnB,YAAY,EAAEK,QAAQ,CAAC;AAExC;;;;;;;;;AASA,OAAO,MAAMe,OAAO,gBAAGzB,MAAM,CAAC0B,UAAU,CAAC,WAAUC,OAGlD;EACC,MAAMC,OAAO,GAAG,OAAOzB,GAAG,CAAC0B,WAAW,CAACF,OAAO,CAAC;EAE/C,OAAOtB,YAAY,CAACiB,EAAE,CAAC;IACrBb,OAAO,EAAGM,OAAO,IACfa,OAAO,CAACX,IAAI,CACVjB,MAAM,CAAC8B,GAAG,CAAEC,IAAI,IAAKA,IAAI,CAACC,GAAG,CAACjB,OAAO,CAACkB,IAAI,CAAC,EAAEC,qBAAqB,IAAI,KAAK,CAAC,EAC5ElC,MAAM,CAACmC,UAAU,CAAC,MAAMnC,MAAM,CAACQ,OAAO,CAAC,IAAI,CAAC,CAAC;GAElD,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;AAWA,OAAO,MAAM4B,QAAQ,GACnBT,OAGa,IAKV1B,KAAK,CAACuB,MAAM,CAACnB,YAAY,EAAEoB,OAAO,CAACE,OAAO,CAAC,CAAC","ignoreList":[]}

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

@@ -7,8 +7,11 @@ import type * as RunnerStorage from "./RunnerStorage.ts";
 import * as Sharding from "./Sharding.ts";
 import { ShardingConfig } from "./ShardingConfig.ts";
 /**
- * @since 4.0.0
+ * Layer of RPC handlers for the runner protocol, forwarding ping, notify, effect,
+ * stream, and envelope requests to `Sharding` and `MessageStorage`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export declare const layerHandlers: Layer.Layer<import("../rpc/Rpc.ts").Handler<"Ping"> | import("../rpc/Rpc.ts").Handler<"Notify"> | import("../rpc/Rpc.ts").Handler<"Effect"> | import("../rpc/Rpc.ts").Handler<"Stream"> | import("../rpc/Rpc.ts").Handler<"Envelope">, never, MessageStorage.MessageStorage | Sharding.Sharding>;
 /**
@@ -17,15 +20,15 @@ export declare const layerHandlers: Layer.Layer<import("../rpc/Rpc.ts").Handler<
  *
  * It also responds to `Ping` requests.
  *
- * @since 4.0.0
  * @category Layers
+ * @since 4.0.0
  */
 export declare const layer: Layer.Layer<never, never, RpcServer.Protocol | Sharding.Sharding | MessageStorage.MessageStorage>;
 /**
  * A `RunnerServer` layer that includes the `Runners` & `Sharding` clients.
  *
- * @since 4.0.0
  * @category Layers
+ * @since 4.0.0
  */
 export declare const layerWithClients: Layer.Layer<Sharding.Sharding | Runners.Runners, never, RpcServer.Protocol | ShardingConfig | Runners.RpcClientProtocol | MessageStorage.MessageStorage | RunnerStorage.RunnerStorage | RunnerHealth.RunnerHealth>;
 /**
@@ -35,8 +38,8 @@ export declare const layerWithClients: Layer.Layer<Sharding.Sharding | Runners.R
  * so this layer can be used to embed a cluster client inside another effect
  * application.
  *
- * @since 4.0.0
  * @category Layers
+ * @since 4.0.0
  */
 export declare const layerClientOnly: Layer.Layer<Sharding.Sharding | Runners.Runners, never, ShardingConfig | Runners.RpcClientProtocol | MessageStorage.MessageStorage | RunnerStorage.RunnerStorage>;
 //# sourceMappingURL=RunnerServer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"RunnerServer.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/RunnerServer.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAGvC,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAA;AAGhD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,KAAK,aAAa,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAIpD;;;GAGG;AACH,eAAO,MAAM,aAAa,kSAmGvB,CAAA;AAIH;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAC7B,KAAK,EACL,KAAK,EACL,SAAS,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,GAAG,cAAc,CAAC,cAAc,CAInC,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,KAAK,CACxC,QAAQ,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,EACnC,KAAK,EACH,SAAS,CAAC,QAAQ,GAClB,cAAc,GACd,OAAO,CAAC,iBAAiB,GACzB,cAAc,CAAC,cAAc,GAC7B,aAAa,CAAC,aAAa,GAC3B,YAAY,CAAC,YAAY,CAI5B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,KAAK,CACvC,QAAQ,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,EACnC,KAAK,EACH,cAAc,GACd,OAAO,CAAC,iBAAiB,GACzB,cAAc,CAAC,cAAc,GAC7B,aAAa,CAAC,aAAa,CAQ9B,CAAA"}
+{"version":3,"file":"RunnerServer.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/RunnerServer.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAGvC,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAA;AAGhD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,KAAK,aAAa,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAIpD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,kSAmGvB,CAAA;AAIH;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAC7B,KAAK,EACL,KAAK,EACL,SAAS,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,GAAG,cAAc,CAAC,cAAc,CAInC,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,KAAK,CACxC,QAAQ,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,EACnC,KAAK,EACH,SAAS,CAAC,QAAQ,GAClB,cAAc,GACd,OAAO,CAAC,iBAAiB,GACzB,cAAc,CAAC,cAAc,GAC7B,aAAa,CAAC,aAAa,GAC3B,YAAY,CAAC,YAAY,CAI5B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,KAAK,CACvC,QAAQ,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,EACnC,KAAK,EACH,cAAc,GACd,OAAO,CAAC,iBAAiB,GACzB,cAAc,CAAC,cAAc,GAC7B,aAAa,CAAC,aAAa,CAQ9B,CAAA"}

package/dist/unstable/cluster/RunnerServer.js

@@ -1,4 +1,28 @@
 /**
+ * The `RunnerServer` module provides the transport-agnostic server side of the
+ * cluster runner protocol. It turns the runner RPC group into handlers that
+ * receive ping, notification, request, stream, and envelope messages from other
+ * runners, then forwards them into `Sharding` and coordinates persisted replies
+ * through `MessageStorage`.
+ *
+ * **Common tasks**
+ *
+ * - Build a runner server once an `RpcServer.Protocol` has been supplied by a
+ *   transport such as HTTP, WebSocket, or sockets
+ * - Provide the complete runner runtime with `Sharding` and `Runners` clients
+ *   using {@link layerWithClients}
+ * - Embed a cluster client without serving runner RPCs or accepting shard
+ *   assignments using {@link layerClientOnly}
+ *
+ * **Gotchas**
+ *
+ * - This module does not choose a wire transport; transport-specific modules
+ *   provide the `RpcServer.Protocol`
+ * - Persisted requests register reply handlers in `MessageStorage` before the
+ *   message is delivered to `Sharding`
+ * - Client-only layers clear the configured runner address, so they can send
+ *   cluster messages but do not register as shard-owning runners
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.js";
@@ -17,8 +41,11 @@ import * as Sharding from "./Sharding.js";
 import { ShardingConfig } from "./ShardingConfig.js";
 const constVoid = /*#__PURE__*/constant(Effect.void);
 /**
- * @since 4.0.0
+ * Layer of RPC handlers for the runner protocol, forwarding ping, notify, effect,
+ * stream, and envelope requests to `Sharding` and `MessageStorage`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerHandlers = /*#__PURE__*/Runners.Rpcs.toLayer(/*#__PURE__*/Effect.gen(function* () {
   const sharding = yield* Sharding.Sharding;
@@ -106,8 +133,8 @@ const constWaitUntilRead = {
  *
  * It also responds to `Ping` requests.
  *
- * @since 4.0.0
  * @category Layers
+ * @since 4.0.0
  */
 export const layer = /*#__PURE__*/RpcServer.layer(Runners.Rpcs, {
   spanPrefix: "RunnerServer",
@@ -116,8 +143,8 @@ export const layer = /*#__PURE__*/RpcServer.layer(Runners.Rpcs, {
 /**
  * A `RunnerServer` layer that includes the `Runners` & `Sharding` clients.
  *
- * @since 4.0.0
  * @category Layers
+ * @since 4.0.0
  */
 export const layerWithClients = /*#__PURE__*/layer.pipe(/*#__PURE__*/Layer.provideMerge(Sharding.layer), /*#__PURE__*/Layer.provideMerge(Runners.layerRpc));
 /**
@@ -127,8 +154,8 @@ export const layerWithClients = /*#__PURE__*/layer.pipe(/*#__PURE__*/Layer.provi
  * so this layer can be used to embed a cluster client inside another effect
  * application.
  *
- * @since 4.0.0
  * @category Layers
+ * @since 4.0.0
  */
 export const layerClientOnly = /*#__PURE__*/Sharding.layer.pipe(/*#__PURE__*/Layer.provideMerge(Runners.layerRpc), /*#__PURE__*/Layer.provide(RunnerHealth.layerNoop), /*#__PURE__*/Layer.updateService(ShardingConfig, config => ({
   ...config,