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

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,

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

@@ -1 +1 @@
-{"version":3,"file":"RunnerServer.js","names":["Effect","Fiber","constant","Layer","Option","Queue","RpcServer","Message","MessageStorage","Reply","RunnerHealth","Runners","Sharding","ShardingConfig","constVoid","void","layerHandlers","Rpcs","toLayer","gen","sharding","storage","Ping","Notify","envelope","notify","_tag","IncomingRequest","respond","lastSentReply","none","IncomingEnvelope","persisted","request","replyEncoded","resume","reply","some","message","orDie","serialize","callback","resume_","parent","getCurrent","onExit","exit","runFork","runForkWith","context","fiber","registerReplyHandler","addObserver","catchTag","constWaitUntilRead","interrupt","andThen","send","isSome","value","Stream","flatMap","make","queue","offerUnsafe","as","pipe","onError","cause","failCause","forkScoped","Envelope","waitUntilRead","layer","spanPrefix","disableTracing","provide","layerWithClients","provideMerge","layerRpc","layerClientOnly","layerNoop","updateService","config","runnerAddress"],"sources":["../../../src/unstable/cluster/RunnerServer.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"RunnerServer.js","names":["Effect","Fiber","constant","Layer","Option","Queue","RpcServer","Message","MessageStorage","Reply","RunnerHealth","Runners","Sharding","ShardingConfig","constVoid","void","layerHandlers","Rpcs","toLayer","gen","sharding","storage","Ping","Notify","envelope","notify","_tag","IncomingRequest","respond","lastSentReply","none","IncomingEnvelope","persisted","request","replyEncoded","resume","reply","some","message","orDie","serialize","callback","resume_","parent","getCurrent","onExit","exit","runFork","runForkWith","context","fiber","registerReplyHandler","addObserver","catchTag","constWaitUntilRead","interrupt","andThen","send","isSome","value","Stream","flatMap","make","queue","offerUnsafe","as","pipe","onError","cause","failCause","forkScoped","Envelope","waitUntilRead","layer","spanPrefix","disableTracing","provide","layerWithClients","provideMerge","layerRpc","layerClientOnly","layerNoop","updateService","config","runnerAddress"],"sources":["../../../src/unstable/cluster/RunnerServer.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AAEzC,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AACvC,SAASC,QAAQ,QAAQ,mBAAmB;AAC5C,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AACvC,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AACvC,OAAO,KAAKC,SAAS,MAAM,qBAAqB;AAEhD,OAAO,KAAKC,OAAO,MAAM,cAAc;AACvC,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AACrD,OAAO,KAAKC,KAAK,MAAM,YAAY;AACnC,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AACjD,OAAO,KAAKC,OAAO,MAAM,cAAc;AAEvC,OAAO,KAAKC,QAAQ,MAAM,eAAe;AACzC,SAASC,cAAc,QAAQ,qBAAqB;AAEpD,MAAMC,SAAS,gBAAGZ,QAAQ,CAACF,MAAM,CAACe,IAAI,CAAC;AAEvC;;;;;;;AAOA,OAAO,MAAMC,aAAa,gBAAGL,OAAO,CAACM,IAAI,CAACC,OAAO,cAAClB,MAAM,CAACmB,GAAG,CAAC,aAAS;EACpE,MAAMC,QAAQ,GAAG,OAAOR,QAAQ,CAACA,QAAQ;EACzC,MAAMS,OAAO,GAAG,OAAOb,cAAc,CAACA,cAAc;EAEpD,OAAO;IACLc,IAAI,EAAEA,CAAA,KAAMtB,MAAM,CAACe,IAAI;IACvBQ,MAAM,EAAEA,CAAC;MAAEC;IAAQ,CAAE,KACnBJ,QAAQ,CAACK,MAAM,CACbD,QAAQ,CAACE,IAAI,KAAK,SAAS,GACvB,IAAInB,OAAO,CAACoB,eAAe,CAAC;MAC5BH,QAAQ;MACRI,OAAO,EAAEd,SAAS;MAClBe,aAAa,EAAEzB,MAAM,CAAC0B,IAAI;KAC3B,CAAC,GACA,IAAIvB,OAAO,CAACwB,gBAAgB,CAAC;MAAEP;IAAQ,CAAE,CAAC,CAC/C;IACHxB,MAAM,EAAEA,CAAC;MAAEgC,SAAS;MAAEC;IAAO,CAAE,KAAI;MACjC,IAAIC,YAAY,GAAwF9B,MAAM,CAC3G0B,IAAI,EAAE;MACT,IAAIK,MAAM,GAAIC,KAA2E,IAAI;QAC3FF,YAAY,GAAG9B,MAAM,CAACiC,IAAI,CAACD,KAAK,CAAC;MACnC,CAAC;MACD,MAAME,OAAO,GAAG,IAAI/B,OAAO,CAACoB,eAAe,CAAC;QAC1CH,QAAQ,EAAES,OAAO;QACjBJ,aAAa,EAAEzB,MAAM,CAAC0B,IAAI,EAAE;QAC5BF,OAAOA,CAACQ,KAAK;UACXD,MAAM,CAACnC,MAAM,CAACuC,KAAK,CAAC9B,KAAK,CAAC+B,SAAS,CAACJ,KAAK,CAAC,CAAC,CAAC;UAC5C,OAAOpC,MAAM,CAACe,IAAI;QACpB;OACD,CAAC;MACF,IAAIiB,SAAS,EAAE;QACb,OAAOhC,MAAM,CAACyC,QAAQ,CAGnBC,OAAO,IAAI;UACZP,MAAM,GAAGO,OAAO;UAChB,MAAMC,MAAM,GAAG1C,KAAK,CAAC2C,UAAU,EAAG;UAClC,MAAMC,MAAM,GACVC,IAGC,IACC;YACF,IAAIA,IAAI,CAACpB,IAAI,KAAK,SAAS,EAAE;cAC3BS,MAAM,CAACW,IAAW,CAAC;YACrB;UACF,CAAC;UACD,MAAMC,OAAO,GAAG/C,MAAM,CAACgD,WAAW,CAACL,MAAM,CAACM,OAAO,CAAC;UAClD,MAAMC,KAAK,GAAGH,OAAO,CAAC1B,OAAO,CAAC8B,oBAAoB,CAACb,OAAO,CAAC,CAAC;UAC5DY,KAAK,CAACE,WAAW,CAACP,MAAM,CAAC;UACzBE,OAAO,CAAC/C,MAAM,CAACqD,QAAQ,CACrBjC,QAAQ,CAACK,MAAM,CAACa,OAAO,EAAEgB,kBAAkB,CAAC,EAC5C,0BAA0B,EAC1B,MAAMtD,MAAM,CAACe,IAAI,CAClB,CAAC,CAACqC,WAAW,CAACP,MAAM,CAAC;UACtB,OAAO5C,KAAK,CAACsD,SAAS,CAACL,KAAK,CAAC;QAC/B,CAAC,CAAC;MACJ;MACA,OAAOlD,MAAM,CAACwD,OAAO,CACnBpC,QAAQ,CAACqC,IAAI,CAACnB,OAAO,CAAC,EACtBtC,MAAM,CAACyC,QAAQ,CAAyDC,OAAO,IAAI;QACjF,IAAItC,MAAM,CAACsD,MAAM,CAACxB,YAAY,CAAC,EAAE;UAC/BQ,OAAO,CAACR,YAAY,CAACyB,KAAK,CAAC;QAC7B,CAAC,MAAM;UACLxB,MAAM,GAAGO,OAAO;QAClB;MACF,CAAC,CAAC,CACH;IACH,CAAC;IACDkB,MAAM,EAAEA,CAAC;MAAE5B,SAAS;MAAEC;IAAO,CAAE,KAC7BjC,MAAM,CAAC6D,OAAO,CACZxD,KAAK,CAACyD,IAAI,EAAyD,EAClEC,KAAK,IAAI;MACR,MAAMzB,OAAO,GAAG,IAAI/B,OAAO,CAACoB,eAAe,CAAC;QAC1CH,QAAQ,EAAES,OAAO;QACjBJ,aAAa,EAAEzB,MAAM,CAAC0B,IAAI,EAAE;QAC5BF,OAAOA,CAACQ,KAAK;UACX,OAAOpC,MAAM,CAAC6D,OAAO,CAACpD,KAAK,CAAC+B,SAAS,CAACJ,KAAK,CAAC,EAAGA,KAAK,IAAI;YACtD/B,KAAK,CAAC2D,WAAW,CAACD,KAAK,EAAE3B,KAAK,CAAC;YAC/B,OAAOpC,MAAM,CAACe,IAAI;UACpB,CAAC,CAAC;QACJ;OACD,CAAC;MACF,OAAOf,MAAM,CAACiE,EAAE,CACdjC,SAAS,GACPhC,MAAM,CAACwD,OAAO,CACZnC,OAAO,CAAC8B,oBAAoB,CAACb,OAAO,CAAC,CAAC4B,IAAI,CACxClE,MAAM,CAACmE,OAAO,CAAEC,KAAK,IAAK/D,KAAK,CAACgE,SAAS,CAACN,KAAK,EAAEK,KAAK,CAAC,CAAC,EACxDpE,MAAM,CAACsE,UAAU,CAClB,EACDlD,QAAQ,CAACK,MAAM,CAACa,OAAO,EAAEgB,kBAAkB,CAAC,CAC7C,GACDlC,QAAQ,CAACqC,IAAI,CAACnB,OAAO,CAAC,EACxByB,KAAK,CACN;IACH,CAAC,CACF;IACHQ,QAAQ,EAAEA,CAAC;MAAE/C;IAAQ,CAAE,KAAKJ,QAAQ,CAACqC,IAAI,CAAC,IAAIlD,OAAO,CAACwB,gBAAgB,CAAC;MAAEP;IAAQ,CAAE,CAAC;GACrF;AACH,CAAC,CAAC,CAAC;AAEH,MAAM8B,kBAAkB,GAAG;EAAEkB,aAAa,EAAE;AAAI,CAAW;AAE3D;;;;;;;;;AASA,OAAO,MAAMC,KAAK,gBAIdnE,SAAS,CAACmE,KAAK,CAAC9D,OAAO,CAACM,IAAI,EAAE;EAChCyD,UAAU,EAAE,cAAc;EAC1BC,cAAc,EAAE;CACjB,CAAC,CAACT,IAAI,cAAC/D,KAAK,CAACyE,OAAO,CAAC5D,aAAa,CAAC,CAAC;AAErC;;;;;;AAMA,OAAO,MAAM6D,gBAAgB,gBASzBJ,KAAK,CAACP,IAAI,cACZ/D,KAAK,CAAC2E,YAAY,CAAClE,QAAQ,CAAC6D,KAAK,CAAC,eAClCtE,KAAK,CAAC2E,YAAY,CAACnE,OAAO,CAACoE,QAAQ,CAAC,CACrC;AAED;;;;;;;;;;AAUA,OAAO,MAAMC,eAAe,gBAOxBpE,QAAQ,CAAC6D,KAAK,CAACP,IAAI,cACrB/D,KAAK,CAAC2E,YAAY,CAACnE,OAAO,CAACoE,QAAQ,CAAC,eACpC5E,KAAK,CAACyE,OAAO,CAAClE,YAAY,CAACuE,SAAS,CAAC,eACrC9E,KAAK,CAAC+E,aAAa,CAACrE,cAAc,EAAGsE,MAAM,KAAM;EAC/C,GAAGA,MAAM;EACTC,aAAa,EAAEhF,MAAM,CAAC0B,IAAI;CAC3B,CAAC,CAAC,CACJ","ignoreList":[]}

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

@@ -1,4 +1,27 @@
 /**
+ * The `RunnerStorage` module defines the persistence boundary used by clustered
+ * runners to register themselves and coordinate shard ownership.
+ *
+ * Implementations keep track of runner metadata, health, machine ids, and shard
+ * locks so a cluster can rebalance work as runners join, leave, or lose their
+ * leases. Production adapters usually implement the string-encoded interface and
+ * adapt it with {@link makeEncoded}; tests and local setups can use
+ * {@link makeMemory}.
+ *
+ * **Common tasks**
+ *
+ * - Register and unregister runners in a shared store
+ * - Read runner health for scheduling and rebalancing decisions
+ * - Acquire, refresh, and release shard locks for distributed processing
+ * - Bridge typed cluster values to string or numeric database representations
+ *
+ * **Gotchas**
+ *
+ * - Shard acquisition may be partial; callers must use the returned shard list
+ * - Refreshing leases is part of keeping shard ownership during rebalancing
+ * - The in-memory implementation is process-local and does not persist runner
+ *   registrations or locks across restarts
+ *
  * @since 4.0.0
  */
 import { type NonEmptyArray } from "../../Array.ts";
@@ -50,14 +73,17 @@ declare const RunnerStorage_base: Context.ServiceClass<RunnerStorage, "effect/cl
  * Represents a generic interface to the persistent storage required by the
  * cluster.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export declare class RunnerStorage extends RunnerStorage_base {
 }
 /**
- * @since 4.0.0
+ * String-encoded runner storage interface used by adapters that persist runner
+ * addresses, runners, machine ids, and shard ids outside the in-memory model.
+ *
  * @category Encoded
+ * @since 4.0.0
  */
 export interface Encoded {
     /**
@@ -96,8 +122,12 @@ export interface Encoded {
     readonly releaseAll: (address: string) => Effect.Effect<void, PersistenceError>;
 }
 /**
- * @since 4.0.0
+ * Adapts an encoded runner storage implementation into `RunnerStorage`, converting
+ * runner addresses, runners, machine ids, and shard ids between typed values and
+ * their string or numeric storage forms.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export declare const makeEncoded: (encoded: Encoded) => {
     /**
@@ -136,8 +166,13 @@ export declare const makeEncoded: (encoded: Encoded) => {
     readonly releaseAll: (address: RunnerAddress) => Effect.Effect<void, PersistenceError>;
 };
 /**
- * @since 4.0.0
+ * Creates an in-memory `RunnerStorage` implementation for tests and local use.
+ *
+ * Registered runners are treated as healthy and shard acquisition is kept only in
+ * process memory.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makeMemory: Effect.Effect<{
     /**
@@ -176,8 +211,10 @@ export declare const makeMemory: Effect.Effect<{
     readonly releaseAll: (address: RunnerAddress) => Effect.Effect<void, PersistenceError>;
 }, never, never>;
 /**
- * @since 4.0.0
+ * Layer that provides the in-memory `RunnerStorage` implementation.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export declare const layerMemory: Layer.Layer<RunnerStorage>;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"RunnerStorage.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/RunnerStorage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RunnerStorage.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/RunnerStorage.ts"],"names":[],"mappings":"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"}

package/dist/unstable/cluster/RunnerStorage.js

@@ -1,4 +1,27 @@
 /**
+ * The `RunnerStorage` module defines the persistence boundary used by clustered
+ * runners to register themselves and coordinate shard ownership.
+ *
+ * Implementations keep track of runner metadata, health, machine ids, and shard
+ * locks so a cluster can rebalance work as runners join, leave, or lose their
+ * leases. Production adapters usually implement the string-encoded interface and
+ * adapt it with {@link makeEncoded}; tests and local setups can use
+ * {@link makeMemory}.
+ *
+ * **Common tasks**
+ *
+ * - Register and unregister runners in a shared store
+ * - Read runner health for scheduling and rebalancing decisions
+ * - Acquire, refresh, and release shard locks for distributed processing
+ * - Bridge typed cluster values to string or numeric database representations
+ *
+ * **Gotchas**
+ *
+ * - Shard acquisition may be partial; callers must use the returned shard list
+ * - Refreshing leases is part of keeping shard ownership during rebalancing
+ * - The in-memory implementation is process-local and does not persist runner
+ *   registrations or locks across restarts
+ *
  * @since 4.0.0
  */
 import { isArrayNonEmpty } from "../../Array.js";
@@ -13,13 +36,17 @@ import * as ShardId from "./ShardId.js";
  * Represents a generic interface to the persistent storage required by the
  * cluster.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class RunnerStorage extends /*#__PURE__*/Context.Service()("effect/cluster/RunnerStorage") {}
 /**
- * @since 4.0.0
+ * Adapts an encoded runner storage implementation into `RunnerStorage`, converting
+ * runner addresses, runners, machine ids, and shard ids between typed values and
+ * their string or numeric storage forms.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const makeEncoded = encoded => RunnerStorage.of({
   getRunners: Effect.gen(function* () {
@@ -53,8 +80,13 @@ export const makeEncoded = encoded => RunnerStorage.of({
   }
 });
 /**
- * @since 4.0.0
+ * Creates an in-memory `RunnerStorage` implementation for tests and local use.
+ *
+ * Registered runners are treated as healthy and shard acquisition is kept only in
+ * process memory.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeMemory = /*#__PURE__*/Effect.gen(function* () {
   const runners = MutableHashMap.empty();
@@ -80,8 +112,10 @@ export const makeMemory = /*#__PURE__*/Effect.gen(function* () {
   });
 });
 /**
- * @since 4.0.0
+ * Layer that provides the in-memory `RunnerStorage` implementation.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerMemory = /*#__PURE__*/Layer.effect(RunnerStorage)(makeMemory);
 // -------------------------------------------------------------------------------------