effect 4.0.5 → 4.0.6

package/dist/cluster/ClusterCron.d.ts

@@ -7,15 +7,37 @@
  * for distributed maintenance work where the job should be owned by the cluster
  * rather than by every runner independently.
  *
+ * With `calculateNextRunFromPrevious`, every run is processed by a single
+ * entity per cron job, so runs never overlap and are caught up in order. The
+ * scheduled time of the current run is available through
+ * `CurrentScheduledTime`.
+ *
  * @stability unstable
  * @since 4.0.0
  */
+import * as Context from "../Context.ts";
 import * as Cron from "../Cron.ts";
+import * as DateTime from "../DateTime.ts";
 import * as Duration from "../Duration.ts";
 import * as Effect from "../Effect.ts";
 import * as Layer from "../Layer.ts";
 import type { Scope } from "../Scope.ts";
 import type { Sharding } from "./Sharding.ts";
+declare const CurrentScheduledTime_base: Context.ServiceClass<CurrentScheduledTime, "effect/cluster/ClusterCron/CurrentScheduledTime", DateTime.Utc>;
+/**
+ * Service tag for the scheduled time of the cron run currently executing.
+ *
+ * **When to use**
+ *
+ * Use to read the time the current run was scheduled for, inside the
+ * `execute` effect of `make`.
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export declare class CurrentScheduledTime extends CurrentScheduledTime_base {
+}
 /**
  * Creates a layer that runs a cron job through the cluster sharding system.
  *
@@ -45,6 +67,11 @@ export declare const make: <E, R>(options: {
      *
      * Defaults to `false`, meaning the next run will be calculated from the
      * current time.
+     *
+     * When enabled, all runs are processed one at a time by a single entity, so
+     * missed runs are caught up in order without overlapping. A run that fails
+     * is retried in place and blocks later runs until it succeeds or is older
+     * than `skipIfOlderThan`.
      */
     readonly calculateNextRunFromPrevious?: boolean | undefined;
     /**
@@ -60,5 +87,6 @@ export declare const make: <E, R>(options: {
      * Defaults to "1 day".
      */
     readonly skipIfOlderThan?: Duration.Input | undefined;
-}) => Layer.Layer<never, never, Sharding | Exclude<R, Scope>>;
+}) => Layer.Layer<never, never, Sharding | Exclude<Exclude<R, CurrentScheduledTime>, Scope>>;
+export {};
 //# sourceMappingURL=ClusterCron.d.ts.map

package/dist/cluster/ClusterCron.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterCron.d.ts","sourceRoot":"","sources":["../../src/cluster/ClusterCron.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,IAAI,MAAM,YAAY,CAAA;AAElC,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC1C,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AAEtC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AAMpC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAKxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAG7C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,WAAW;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAE3C;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAExC;;;;;;;;OAQG;IACH,QAAQ,CAAC,4BAA4B,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAE3D;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;CACtD,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAuEzD,CAAA"}
+{"version":3,"file":"ClusterCron.d.ts","sourceRoot":"","sources":["../../src/cluster/ClusterCron.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,OAAO,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,IAAI,MAAM,YAAY,CAAA;AAClC,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC1C,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC1C,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AAEtC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AAMpC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAKxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;;AAG7C;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAqB,SAAQ,yBAGY;CAAG;AAEzD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,WAAW;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAE3C;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAExC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,4BAA4B,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAE3D;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;CACtD,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,oBAAoB,CAAC,EAAE,KAAK,CAAC,CA0FxF,CAAA"}

package/dist/cluster/ClusterCron.js

@@ -7,9 +7,15 @@
  * for distributed maintenance work where the job should be owned by the cluster
  * rather than by every runner independently.
  *
+ * With `calculateNextRunFromPrevious`, every run is processed by a single
+ * entity per cron job, so runs never overlap and are caught up in order. The
+ * scheduled time of the current run is available through
+ * `CurrentScheduledTime`.
+ *
  * @stability unstable
  * @since 4.0.0
  */
+import * as Context from "../Context.js";
 import * as Cron from "../Cron.js";
 import * as DateTime from "../DateTime.js";
 import * as Duration from "../Duration.js";
@@ -26,6 +32,19 @@ import { Persisted, Uninterruptible } from "./ClusterSchema.js";
 import * as DeliverAt from "./DeliverAt.js";
 import * as Entity from "./Entity.js";
 import * as Singleton from "./Singleton.js";
+/**
+ * Service tag for the scheduled time of the cron run currently executing.
+ *
+ * **When to use**
+ *
+ * Use to read the time the current run was scheduled for, inside the
+ * `execute` effect of `make`.
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export class CurrentScheduledTime extends /*#__PURE__*/Context.Service()("effect/cluster/ClusterCron/CurrentScheduledTime") {}
 /**
  * Creates a layer that runs a cron job through the cluster sharding system.
  *
@@ -40,60 +59,73 @@ import * as Singleton from "./Singleton.js";
  * @since 4.0.0
  */
 export const make = options => {
+  const fromPrevious = options.calculateNextRunFromPrevious === true;
+  const nextRun = after => DateTime.fromDateUnsafe(Cron.next(options.cron, after));
   const CronEntity = Entity.make(`ClusterCron/${options.name}`, [Rpc.make("run", {
     payload: CronPayload
-  }).annotate(Persisted, true).annotate(Uninterruptible, true)]).annotate(ClusterSchema.ShardGroup, () => options.shardGroup ?? "default").annotate(ClusterSchema.ClientTracingEnabled, false);
-  const InitialRun = Singleton.make(`ClusterCron/${options.name}`, Effect.gen(function* () {
-    const now = yield* DateTime.now;
-    const next = DateTime.fromDateUnsafe(Cron.next(options.cron, now));
-    const entityId = options.calculateNextRunFromPrevious ? "initial" : DateTime.formatIso(next);
-    const client = (yield* CronEntity.client)(entityId);
-    yield* client.run({
-      dateTime: next
-    }, {
-      discard: true
-    });
+  }).annotate(Persisted, true).annotate(Uninterruptible, true), Rpc.make("start").annotate(Persisted, true)]).annotate(ClusterSchema.ShardGroup, () => options.shardGroup ?? "default").annotate(ClusterSchema.ClientTracingEnabled, false);
+  // with `calculateNextRunFromPrevious`, every run shares the executor address
+  const send = dateTime => Effect.flatMap(CronEntity.client, makeClient => fromPrevious ? makeClient(executorId).run(new CronPayload({
+    dateTime,
+    executor: true
   }), {
+    discard: true
+  }) : makeClient(DateTime.formatIso(dateTime)).run(new CronPayload({
+    dateTime
+  }), {
+    discard: true
+  }));
+  const schedule = dateTime => send(dateTime).pipe(withRetry("Failed to schedule next run, retrying"));
+  const InitialRun = Singleton.make(`ClusterCron/${options.name}`, fromPrevious
+  // the executor schedules the next run if its chain has been lost.
+  // `start` has no primary key, so each retry is a new message
+  ? Effect.flatMap(CronEntity.client, makeClient => makeClient(executorId).start()).pipe(withRetry("Failed to start cron job, retrying")) : Effect.flatMap(DateTime.now, now => send(nextRun(now)).pipe(withRetry("Failed to schedule initial run, retrying"))), {
     shardGroup: options.shardGroup
   });
   const skipIfOlderThan = Option.fromUndefinedOr(options.skipIfOlderThan).pipe(Option.map(Duration.fromInputUnsafe), Option.getOrElse(() => Duration.days(1)));
-  const effect = Effect.fnUntraced(function* (dateTime) {
+  const execute = Effect.fnUntraced(function* (dateTime) {
     const now = yield* DateTime.now;
     if (DateTime.isLessThan(dateTime, DateTime.subtractDuration(now, skipIfOlderThan))) {
       return;
     }
-    return yield* options.execute;
+    return yield* Effect.provideService(options.execute, CurrentScheduledTime, dateTime);
   }, Effect.orDie);
   const EntityLayer = CronEntity.toLayer(Effect.gen(function* () {
-    const makeClient = yield* CronEntity.client;
+    const address = yield* Entity.CurrentAddress;
+    // runs are processed one at a time, so a run processed before `start`
+    // means the chain is alive
+    let processedRun = false;
     return {
-      run: request => Effect.onExitPrimitive(effect(request.payload.dateTime), Effect.fnUntraced(function* (exit) {
-        if (Exit.isFailure(exit)) {
-          yield* Effect.logWarning(exit.cause);
+      run: request => {
+        const dateTime = request.payload.dateTime;
+        if (fromPrevious && address.entityId !== executorId) {
+          // a run scheduled by an earlier release joins the executor's chain
+          return schedule(dateTime);
         }
-        const now = yield* DateTime.now;
-        const next = DateTime.fromDateUnsafe(Cron.next(options.cron, options.calculateNextRunFromPrevious ? request.payload.dateTime : now));
-        const client = makeClient(DateTime.formatIso(next));
-        return yield* client.run({
-          dateTime: next
-        }, {
-          discard: true
-        }).pipe(Effect.tapCause(cause => Effect.logWarning("Failed to schedule next run, retrying", cause)), Effect.sandbox, Effect.retry(retryPolicy), Effect.orDie);
-      }), true).pipe(Effect.annotateLogs({
-        module: "effect/cluster/ClusterCron",
-        name: options.name,
-        dateTime: request.payload.dateTime
-      }))
+        processedRun = true;
+        return Effect.onExitPrimitive(execute(dateTime), exit => Effect.andThen(Exit.isFailure(exit) ? Effect.logWarning(exit.cause) : Effect.void, fromPrevious ? schedule(nextRun(dateTime)) : Effect.flatMap(DateTime.now, now => schedule(nextRun(now)))), true).pipe(Effect.annotateLogs({
+          module: "effect/cluster/ClusterCron",
+          name: options.name,
+          dateTime
+        }));
+      },
+      start: () => processedRun ? Effect.void
+      // deduplicated against the pending run if the chain is alive
+      : Effect.flatMap(DateTime.now, now => schedule(nextRun(now)))
     };
   }));
   return Layer.merge(InitialRun, EntityLayer);
 };
+const executorId = "executor";
 const retryPolicy = /*#__PURE__*/Schedule.min([/*#__PURE__*/Schedule.exponential(200, 1.5), /*#__PURE__*/Schedule.spaced("1 minute")]);
+const withRetry = message => self => self.pipe(Effect.tapCause(cause => Effect.logWarning(message, cause)), Effect.sandbox, Effect.retry(retryPolicy), Effect.orDie);
 class CronPayload extends /*#__PURE__*/Schema.Class("effect/cluster/ClusterCron/CronPayload")({
-  dateTime: Schema.DateTimeUtc
+  dateTime: Schema.DateTimeUtc,
+  // set for runs sent to the executor, which share one entity address
+  executor: /*#__PURE__*/Schema.optional(Schema.Boolean)
 }) {
   [PrimaryKey.symbol]() {
-    return "";
+    return this.executor ? DateTime.formatIso(this.dateTime) : "";
   }
   [DeliverAt.symbol]() {
     return this.dateTime;

package/dist/cluster/ClusterCron.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterCron.js","names":[],"sources":["../../src/cluster/ClusterCron.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"ClusterCron.js","names":[],"sources":["../../src/cluster/ClusterCron.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/cluster/ClusterMetrics.d.ts

@@ -1,10 +1,11 @@
 /**
  * Standard metric definitions used by the unstable cluster runtime. The gauges
- * track runner-local entities, singleton processes, registered runners,
- * healthy runners, and acquired shards.
+ * track runner-local entities, entity mailbox sizes, singleton processes,
+ * registered runners, healthy runners, acquired shards, and shards being
+ * released. The timer tracks shard release duration.
  *
  * This module only defines the metric handles. The runtime components that
- * manage entities, runners, singletons, and sharding update these gauges while
+ * manage entities, runners, singletons, and sharding update these metrics while
  * the cluster is running.
  *
  * @stability unstable
@@ -22,13 +23,13 @@ import * as Metric from "../Metric.ts";
  *
  * **Details**
  *
- * Bigint gauge named `effect_cluster_entities`, updated with the entity type as
- * a metric tag.
+ * Bigint gauge named `effect_cluster_entities`, tagged with the entity type.
+ * Each entity manager registers a series that reads its active entity count
+ * when metrics are snapshotted, and removes it when the manager shuts down.
  *
  * **Gotchas**
  *
- * This gauge is runner-local and sampled by the entity manager loop. Aggregate
- * across runners and expect up to roughly one polling interval of lag.
+ * This gauge is runner-local. Aggregate across runners.
  *
  * @see {@link singletons} for singleton process counts on the current runner
  * @see {@link shards} for shard ownership on the current runner
@@ -38,6 +39,84 @@ import * as Metric from "../Metric.ts";
  * @since 4.0.0
  */
 export declare const entities: Metric.Gauge<bigint>;
+/**
+ * Represents a gauge tracking the mailbox size of each entity resident on the
+ * current runner.
+ *
+ * **When to use**
+ *
+ * Use to find entities whose mailboxes back up, before sends start failing
+ * with `MailboxFull`.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_entity_mailbox_size`, with one series per
+ * resident entity tagged with `type`, `id` and `shard`. The value is the
+ * number the mailbox capacity check compares against: requests admitted to the
+ * entity, whether queued or in flight, excluding internal keep-alive requests.
+ *
+ * The value is read when metrics are snapshotted, so it adds no work per
+ * message. Each series is removed when its entity is released.
+ *
+ * **Gotchas**
+ *
+ * Off by default. Enable it with `ShardingConfig.entityMailboxMetrics` or the
+ * `mailboxMetrics` option when registering an entity. One series per resident
+ * entity can mean many series on busy runners.
+ *
+ * An entity keeps reporting while it drains in-flight requests during
+ * shutdown. `Metric.update` and `Metric.modify` on this gauge do nothing for
+ * series the runtime registered.
+ *
+ * Like the other runner gauges it has no runner attribute: runners sharing a
+ * registry without distinct metric attributes overwrite each other's series.
+ *
+ * @see {@link entities} for the number of resident entities per type
+ * @see {@link entityMailboxSizeMax} for the always-on per-type maximum
+ *
+ * @stability unstable
+ * @category metrics
+ * @since 4.0.6
+ */
+export declare const entityMailboxSize: Metric.Gauge<bigint>;
+/**
+ * Represents a gauge tracking the largest mailbox size among the entities of
+ * each type resident on the current runner.
+ *
+ * **When to use**
+ *
+ * Use to alert on entity types whose mailboxes back up, before sends start
+ * failing with `MailboxFull`, without paying for a series per entity.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_entity_mailbox_size_max`, with one series
+ * per registered entity type tagged with `type`. The value is the largest
+ * mailbox size that {@link entityMailboxSize} would report for the type,
+ * including entities draining in-flight requests during shutdown, or `0` when
+ * the type has no resident entities.
+ *
+ * The value is computed when metrics are snapshotted, by visiting each
+ * resident entity of the type, so it adds no work per message. Entities
+ * draining during shutdown keep their slot until they finish, so the visit is
+ * bounded by `ShardingConfig.maxResidentEntities` across all types, unless it
+ * is `"unbounded"`. The series is removed when the entity type shuts down.
+ *
+ * **Gotchas**
+ *
+ * Always on. `Metric.update` and `Metric.modify` on this gauge do nothing for
+ * series the runtime registered.
+ *
+ * Like the other runner gauges it has no runner attribute: runners sharing a
+ * registry without distinct metric attributes overwrite each other's series.
+ *
+ * @see {@link entityMailboxSize} for the opt-in per-entity mailbox sizes
+ *
+ * @stability unstable
+ * @category metrics
+ * @since 4.0.6
+ */
+export declare const entityMailboxSizeMax: Metric.Gauge<bigint>;
 /**
  * Creates a gauge tracking the number of singleton processes currently running on the
  * current runner.
@@ -111,4 +190,61 @@ export declare const runnersHealthy: Metric.Gauge<bigint>;
  * @since 4.0.0
  */
 export declare const shards: Metric.Gauge<bigint>;
+/**
+ * Represents a gauge tracking the number of shards the current runner is still
+ * releasing.
+ *
+ * **When to use**
+ *
+ * Use to detect shard releases that stall during rebalancing, shutdown handoff
+ * or lock storage failures.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_shards_releasing`, updated with the number
+ * of distinct shards being released. A shard counts from the moment it is no
+ * longer acquired until its entities and singletons have stopped and its lock
+ * is released, including waits for lock storage to recover and release
+ * retries.
+ *
+ * **Gotchas**
+ *
+ * Positive values are normal while shards move; alert only when the value
+ * stays positive. It does not reflect lock ownership, and reacquisition can
+ * stay blocked briefly after it returns to zero, while a forced release
+ * finishes its bookkeeping.
+ *
+ * Like the other runner gauges it assumes one runner per process: runners
+ * sharing a registry without distinct metric attributes overwrite each other's
+ * value.
+ *
+ * @stability unstable
+ * @category metrics
+ * @since 4.1.0
+ */
+export declare const shardsReleasing: Metric.Gauge<bigint>;
+/**
+ * Represents a timer tracking how long the current runner takes to release a
+ * shard after reassignment, lock loss or shutdown handoff.
+ *
+ * **When to use**
+ *
+ * Use to observe shard handoff latency during rebalancing, shutdown, or lock
+ * storage failures.
+ *
+ * **Details**
+ *
+ * Millisecond timer named `effect_cluster_shard_release`. Each sample covers
+ * entity teardown, retries and any wait for shard lock storage to recover.
+ *
+ * **Gotchas**
+ *
+ * Only completed releases are recorded. Interrupted releases and forced
+ * releases after lock storage becomes unhealthy are not.
+ *
+ * @stability unstable
+ * @category metrics
+ * @since 4.0.0
+ */
+export declare const shardReleaseDuration: Metric.Histogram<import("../Duration.ts").Duration>;
 //# sourceMappingURL=ClusterMetrics.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ClusterMetrics.d.ts","sourceRoot":"","sources":["../../src/cluster/ClusterMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,QAAQ,sBAA4D,CAAA;AAEjF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,sBAA8D,CAAA;AAErF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO,sBAA2D,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,sBAAmE,CAAA;AAE9F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,MAAM,sBAA0D,CAAA"}
+{"version":3,"file":"ClusterMetrics.d.ts","sourceRoot":"","sources":["../../src/cluster/ClusterMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,QAAQ,sBAA4D,CAAA;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,iBAAiB,sBAAuE,CAAA;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,oBAAoB,sBAA2E,CAAA;AAE5G;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,sBAA8D,CAAA;AAErF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO,sBAA2D,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,sBAAmE,CAAA;AAE9F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,MAAM,sBAA0D,CAAA;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,eAAe,sBAAoE,CAAA;AAEhG;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,oBAAoB,qDAE/B,CAAA"}

package/dist/cluster/ClusterMetrics.js

@@ -1,10 +1,11 @@
 /**
  * Standard metric definitions used by the unstable cluster runtime. The gauges
- * track runner-local entities, singleton processes, registered runners,
- * healthy runners, and acquired shards.
+ * track runner-local entities, entity mailbox sizes, singleton processes,
+ * registered runners, healthy runners, acquired shards, and shards being
+ * released. The timer tracks shard release duration.
  *
  * This module only defines the metric handles. The runtime components that
- * manage entities, runners, singletons, and sharding update these gauges while
+ * manage entities, runners, singletons, and sharding update these metrics while
  * the cluster is running.
  *
  * @stability unstable
@@ -22,13 +23,13 @@ import * as Metric from "../Metric.js";
  *
  * **Details**
  *
- * Bigint gauge named `effect_cluster_entities`, updated with the entity type as
- * a metric tag.
+ * Bigint gauge named `effect_cluster_entities`, tagged with the entity type.
+ * Each entity manager registers a series that reads its active entity count
+ * when metrics are snapshotted, and removes it when the manager shuts down.
  *
  * **Gotchas**
  *
- * This gauge is runner-local and sampled by the entity manager loop. Aggregate
- * across runners and expect up to roughly one polling interval of lag.
+ * This gauge is runner-local. Aggregate across runners.
  *
  * @see {@link singletons} for singleton process counts on the current runner
  * @see {@link shards} for shard ownership on the current runner
@@ -40,6 +41,88 @@ import * as Metric from "../Metric.js";
 export const entities = /*#__PURE__*/Metric.gauge("effect_cluster_entities", {
   bigint: true
 });
+/**
+ * Represents a gauge tracking the mailbox size of each entity resident on the
+ * current runner.
+ *
+ * **When to use**
+ *
+ * Use to find entities whose mailboxes back up, before sends start failing
+ * with `MailboxFull`.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_entity_mailbox_size`, with one series per
+ * resident entity tagged with `type`, `id` and `shard`. The value is the
+ * number the mailbox capacity check compares against: requests admitted to the
+ * entity, whether queued or in flight, excluding internal keep-alive requests.
+ *
+ * The value is read when metrics are snapshotted, so it adds no work per
+ * message. Each series is removed when its entity is released.
+ *
+ * **Gotchas**
+ *
+ * Off by default. Enable it with `ShardingConfig.entityMailboxMetrics` or the
+ * `mailboxMetrics` option when registering an entity. One series per resident
+ * entity can mean many series on busy runners.
+ *
+ * An entity keeps reporting while it drains in-flight requests during
+ * shutdown. `Metric.update` and `Metric.modify` on this gauge do nothing for
+ * series the runtime registered.
+ *
+ * Like the other runner gauges it has no runner attribute: runners sharing a
+ * registry without distinct metric attributes overwrite each other's series.
+ *
+ * @see {@link entities} for the number of resident entities per type
+ * @see {@link entityMailboxSizeMax} for the always-on per-type maximum
+ *
+ * @stability unstable
+ * @category metrics
+ * @since 4.0.6
+ */
+export const entityMailboxSize = /*#__PURE__*/Metric.gauge("effect_cluster_entity_mailbox_size", {
+  bigint: true
+});
+/**
+ * Represents a gauge tracking the largest mailbox size among the entities of
+ * each type resident on the current runner.
+ *
+ * **When to use**
+ *
+ * Use to alert on entity types whose mailboxes back up, before sends start
+ * failing with `MailboxFull`, without paying for a series per entity.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_entity_mailbox_size_max`, with one series
+ * per registered entity type tagged with `type`. The value is the largest
+ * mailbox size that {@link entityMailboxSize} would report for the type,
+ * including entities draining in-flight requests during shutdown, or `0` when
+ * the type has no resident entities.
+ *
+ * The value is computed when metrics are snapshotted, by visiting each
+ * resident entity of the type, so it adds no work per message. Entities
+ * draining during shutdown keep their slot until they finish, so the visit is
+ * bounded by `ShardingConfig.maxResidentEntities` across all types, unless it
+ * is `"unbounded"`. The series is removed when the entity type shuts down.
+ *
+ * **Gotchas**
+ *
+ * Always on. `Metric.update` and `Metric.modify` on this gauge do nothing for
+ * series the runtime registered.
+ *
+ * Like the other runner gauges it has no runner attribute: runners sharing a
+ * registry without distinct metric attributes overwrite each other's series.
+ *
+ * @see {@link entityMailboxSize} for the opt-in per-entity mailbox sizes
+ *
+ * @stability unstable
+ * @category metrics
+ * @since 4.0.6
+ */
+export const entityMailboxSizeMax = /*#__PURE__*/Metric.gauge("effect_cluster_entity_mailbox_size_max", {
+  bigint: true
+});
 /**
  * Creates a gauge tracking the number of singleton processes currently running on the
  * current runner.
@@ -121,4 +204,65 @@ export const runnersHealthy = /*#__PURE__*/Metric.gauge("effect_cluster_runners_
 export const shards = /*#__PURE__*/Metric.gauge("effect_cluster_shards", {
   bigint: true
 });
+/**
+ * Represents a gauge tracking the number of shards the current runner is still
+ * releasing.
+ *
+ * **When to use**
+ *
+ * Use to detect shard releases that stall during rebalancing, shutdown handoff
+ * or lock storage failures.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_shards_releasing`, updated with the number
+ * of distinct shards being released. A shard counts from the moment it is no
+ * longer acquired until its entities and singletons have stopped and its lock
+ * is released, including waits for lock storage to recover and release
+ * retries.
+ *
+ * **Gotchas**
+ *
+ * Positive values are normal while shards move; alert only when the value
+ * stays positive. It does not reflect lock ownership, and reacquisition can
+ * stay blocked briefly after it returns to zero, while a forced release
+ * finishes its bookkeeping.
+ *
+ * Like the other runner gauges it assumes one runner per process: runners
+ * sharing a registry without distinct metric attributes overwrite each other's
+ * value.
+ *
+ * @stability unstable
+ * @category metrics
+ * @since 4.1.0
+ */
+export const shardsReleasing = /*#__PURE__*/Metric.gauge("effect_cluster_shards_releasing", {
+  bigint: true
+});
+/**
+ * Represents a timer tracking how long the current runner takes to release a
+ * shard after reassignment, lock loss or shutdown handoff.
+ *
+ * **When to use**
+ *
+ * Use to observe shard handoff latency during rebalancing, shutdown, or lock
+ * storage failures.
+ *
+ * **Details**
+ *
+ * Millisecond timer named `effect_cluster_shard_release`. Each sample covers
+ * entity teardown, retries and any wait for shard lock storage to recover.
+ *
+ * **Gotchas**
+ *
+ * Only completed releases are recorded. Interrupted releases and forced
+ * releases after lock storage becomes unhealthy are not.
+ *
+ * @stability unstable
+ * @category metrics
+ * @since 4.0.0
+ */
+export const shardReleaseDuration = /*#__PURE__*/Metric.timer("effect_cluster_shard_release", {
+  description: "Time taken to release a shard, including entity teardown, retries and lock storage recovery"
+});
 //# sourceMappingURL=ClusterMetrics.js.map

package/dist/cluster/ClusterMetrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterMetrics.js","names":[],"sources":["../../src/cluster/ClusterMetrics.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;AAYA,OAAO,KAAK,MAAM,MAAM,cAAc;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,OAAO,MAAM,QAAQ,gBAAG,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAEjF;;;;;;;;AAQA,OAAO,MAAM,UAAU,gBAAG,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAErF;;;;;;;;;;;;;;;;;AAiBA,OAAO,MAAM,OAAO,gBAAG,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAM,cAAc,gBAAG,MAAM,CAAC,KAAK,CAAC,gCAAgC,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAM,MAAM,gBAAG,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC","ignoreList":[]}
+{"version":3,"file":"ClusterMetrics.js","names":[],"sources":["../../src/cluster/ClusterMetrics.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;AAaA,OAAO,KAAK,MAAM,MAAM,cAAc;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,OAAO,MAAM,QAAQ,gBAAG,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,OAAO,MAAM,iBAAiB,gBAAG,MAAM,CAAC,KAAK,CAAC,oCAAoC,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,OAAO,MAAM,oBAAoB,gBAAG,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAE5G;;;;;;;;AAQA,OAAO,MAAM,UAAU,gBAAG,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAErF;;;;;;;;;;;;;;;;;AAiBA,OAAO,MAAM,OAAO,gBAAG,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAM,cAAc,gBAAG,MAAM,CAAC,KAAK,CAAC,gCAAgC,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAM,MAAM,gBAAG,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,OAAO,MAAM,eAAe,gBAAG,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE;EAAE,MAAM,EAAE;AAAI,CAAE,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAM,oBAAoB,gBAAG,MAAM,CAAC,KAAK,CAAC,8BAA8B,EAAE;EAC/E,WAAW,EAAE;CACd,CAAC","ignoreList":[]}

package/dist/cluster/ClusterWorkflowEngine.d.ts

@@ -4,7 +4,7 @@ import * as Layer from "../Layer.ts";
 import * as Option from "../Option.ts";
 import * as Schedule from "../Schedule.ts";
 import * as Schema from "../Schema.ts";
-import type * as Scope from "../Scope.ts";
+import * as Scope from "../Scope.ts";
 import * as Activity from "../workflow/Activity.ts";
 import * as DurableClock from "../workflow/DurableClock.ts";
 import * as DurableDeferred from "../workflow/DurableDeferred.ts";

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

@@ -1 +1 @@
-{"version":3,"file":"ClusterWorkflowEngine.d.ts","sourceRoot":"","sources":["../../src/cluster/ClusterWorkflowEngine.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AACtC,OAAO,KAAK,IAAI,MAAM,YAAY,CAAA;AAGlC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AACpC,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AAMtC,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC1C,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AACtC,OAAO,KAAK,KAAK,KAAK,MAAM,aAAa,CAAA;AAEzC,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;AAW/D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGpD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAGzC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;2DA4xBf,CAAA;AA4JF;;;;;;;;;;;;GAYG;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/cluster/ClusterWorkflowEngine.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AACtC,OAAO,KAAK,IAAI,MAAM,YAAY,CAAA;AAGlC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AACpC,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AAMtC,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC1C,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AACtC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AAEpC,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;AAW/D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGpD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAGzC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;2DA6zBf,CAAA;AAsKF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAC7B,cAAc,CAAC,cAAc,EAC7B,KAAK,EACL,QAAQ,CAAC,QAAQ,GAAG,cAAc,CAGnC,CAAA"}