effect 4.0.7 → 4.1.1

package/src/cli/Primitive.ts

@@ -20,6 +20,7 @@ import { format } from "../Formatter.ts"
 import { identity } from "../Function.ts"
 import * as Path_ from "../Path.ts"
 import * as Redacted_ from "../Redacted.ts"
+import * as Result from "../Result.ts"
 import * as Schema from "../Schema.ts"
 import type { Formatter } from "../SchemaIssue.ts"
 import type * as Struct from "../Struct.ts"
@@ -45,6 +46,7 @@ const TypeId = "~effect/cli/Primitive"
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -157,6 +159,7 @@ const makeSchemaPrimitive = <T>(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -203,6 +206,7 @@ export const Boolean: Primitive<boolean> = makeSchemaPrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -248,6 +252,7 @@ export const Finite: Primitive<number> = makeSchemaPrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -293,6 +298,7 @@ export const Int: Primitive<number> = makeSchemaPrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -337,6 +343,7 @@ export const Date: Primitive<globalThis.Date> = makeSchemaPrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -379,6 +386,7 @@ export const String: Primitive<string> = makePrimitive("String", (value) => Effe
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -470,6 +478,7 @@ export type PathType = "file" | "directory" | "either"
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -560,6 +569,7 @@ export const Path = (
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -608,6 +618,7 @@ export const Redacted: Primitive<Redacted_.Redacted<string>> = makePrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -686,7 +697,7 @@ export type FileParseOptions = {
 const fileParsers: Record<string, (content: string) => unknown> = {
   ini: (content: string) => Ini.parse(content),
   json: (content: string) => JSON.parse(content),
-  toml: (content: string) => Toml.parse(content),
+  toml: (content: string) => Result.getOrThrow(Toml.parse(content)),
   yml: (content: string) => Yaml.parse(content),
   yaml: (content: string) => Yaml.parse(content)
 }
@@ -718,6 +729,7 @@ const fileParsers: Record<string, (content: string) => unknown> = {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -795,6 +807,7 @@ export type FileSchemaOptions = Struct.Simplify<
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -862,6 +875,7 @@ export const FileSchema = <A>(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -923,6 +937,7 @@ export const KeyValuePair: Primitive<Record<string, string>> = makePrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void

package/src/cli/Prompt.ts

@@ -791,6 +791,7 @@ export declare namespace All {
  * const terminal = Terminal.make({
  *   columns: Effect.succeed(80),
  *   rows: Effect.succeed(24),
+ *   size: Effect.die("unused"),
  *   readInput: Effect.succeed({} as never),
  *   readLine: Effect.die("unused"),
  *   display: () => Effect.void

package/src/cli/internal/help.ts

@@ -96,7 +96,7 @@ const collectDeclaredGlobalFlags = (command: Command.Any): ReadonlyArray<GlobalF
   return dedupeGlobalFlags(collected)
 }
 
-const getSharedFlagsForCommandPath = (
+const getInheritedFlagsForCommandPath = (
   commands: ReadonlyArray<Command.Any>,
   currentFlags: ReadonlyArray<FlagDoc>
 ): ReadonlyArray<FlagDoc> => {
@@ -105,7 +105,7 @@ const getSharedFlagsForCommandPath = (
   }
 
   const seen = new Set(currentFlags.map((flag) => flag.name))
-  const sharedFlags: Array<FlagDoc> = []
+  const inheritedFlags: Array<FlagDoc> = []
 
   for (const ancestor of commands.slice(0, -1)) {
     const ancestorImpl = toImpl(ancestor)
@@ -116,19 +116,16 @@ const getSharedFlagsForCommandPath = (
         if (seen.has(single.name)) {
           continue
         }
-        // Hidden ancestor flags are excluded from the shared-flags section
-        // of subcommand help, the same way they're excluded from the owning
-        // command's own help output.
         if (single.hidden) {
           continue
         }
         seen.add(single.name)
-        sharedFlags.push(toFlagDoc(single, metadata))
+        inheritedFlags.push(toFlagDoc(single, metadata))
       }
     }
   }
 
-  return sharedFlags
+  return inheritedFlags
 }
 
 /**
@@ -160,7 +157,7 @@ export const getHelpForCommandPath = <Name extends string, Input, E, R, ContextI
 
     const baseDoc = toImpl(currentCommand).buildHelpDoc(commandPath)
 
-    const sharedFlags = getSharedFlagsForCommandPath(commands, baseDoc.flags)
+    const inheritedFlags = getInheritedFlagsForCommandPath(commands, baseDoc.flags)
 
     const flags = getGlobalFlagsForCommandPath(command, commandPath, builtIns)
     const globalFlagDocs: Array<FlagDoc> = []
@@ -179,5 +176,20 @@ export const getHelpForCommandPath = <Name extends string, Input, E, R, ContextI
       }
     }
 
-    return { ...baseDoc, flags: [...sharedFlags, ...baseDoc.flags], globalFlags: globalFlagDocs }
+    // Globals accumulate along the path, so the deepest declaring scope lists them all.
+    let scopeLength = 1
+    for (let i = commands.length - 1; i > 0; i--) {
+      if (toImpl(commands[i]).globalFlags.length > 0) {
+        scopeLength = i + 1
+        break
+      }
+    }
+
+    return {
+      ...baseDoc,
+      inheritedFlags,
+      globalFlags: globalFlagDocs,
+      globalFlagsScope: commandPath.slice(0, scopeLength),
+      commandPath
+    }
   })

package/src/cluster/ClusterWorkflowEngine.ts

@@ -535,14 +535,15 @@ export const make = Effect.gen(function*() {
                     if (instance.abandoned) {
                       instance.suspended = false
                     }
+                    // Abandoned runs never wake the parent; another owner replays them.
+                    const resumeParent = parent && !parent.detached && !instance.abandoned
+                      ? ensureSuccess(sendResumeParent(parent, executionId))
+                      : Effect.void
                     if (
                       !instance.suspended &&
                       !instance.abandoned &&
                       !(suspendOnFailure && exit._tag === "Failure")
                     ) {
-                      const resumeParent = parent && !parent.detached
-                        ? ensureSuccess(sendResumeParent(parent, executionId))
-                        : Effect.void
                       if (exit._tag === "Success" || !Cause.hasInterruptsOnly(exit.cause)) {
                         return resumeParent
                       }
@@ -568,9 +569,13 @@ export const make = Effect.gen(function*() {
                         }
                         instance.suspended = false
                         instance.interrupted = true
-                        return Effect.andThen(
-                          Effect.ignore(clearClock({ workflow, executionId })),
-                          Effect.withFiber<void>((fiber) => Effect.interruptible(Fiber.interrupt(fiber)))
+                        // The interrupt completes the run, so wake the parent
+                        // to observe it.
+                        return Effect.ignore(clearClock({ workflow, executionId })).pipe(
+                          Effect.andThen(resumeParent),
+                          Effect.andThen(
+                            Effect.withFiber<void>((fiber) => Effect.interruptible(Fiber.interrupt(fiber)))
+                          )
                         )
                       }),
                       Effect.orDie
@@ -760,7 +765,7 @@ export const make = Effect.gen(function*() {
         // A pending interrupt replays only to rebuild compensations, so it must
         // not run new activities. Finalizers run once `interrupted` is set.
         if (!instance.interrupted && (yield* interruptPending(instance))) {
-          const reply = yield* Effect.orDie(requestReply({
+          const reply = yield* retryPersistence(requestReply({
             workflow: instance.workflow,
             entityType: `Workflow/${instance.workflow._tag}`,
             executionId: instance.executionId,
@@ -777,7 +782,7 @@ export const make = Effect.gen(function*() {
           if (!activities.has(activityId)) {
             activities.set(activityId, { activity, context: services })
           }
-          const result = yield* Effect.orDie(
+          const result = yield* retryPersistence(
             client.activity({
               name: activity.name,
               attempt,
@@ -917,6 +922,15 @@ const retryPolicy = Schedule.min([
   Schedule.spaced("1 minute")
 ])
 
+// A transient storage failure must not become the workflow result. Requests
+// are saved under a primary key, so a retry after a lost acknowledgement is
+// deduplicated instead of running the activity again.
+const retryPersistence = <A, E extends { readonly _tag: string }, R>(effect: Effect.Effect<A, E, R>) =>
+  effect.pipe(
+    Effect.retry({ schedule: retryPolicy, while: (e) => e._tag === "PersistenceError" }),
+    Effect.orDie
+  )
+
 // A cluster abandonment means this owner can no longer complete the effect, so
 // retrying it would only wait on a retired run. Re-raise it as an annotated
 // interrupt, so the activation can unwind and its shard can be released.

package/src/cluster/Reply.ts

@@ -220,7 +220,7 @@ export class Chunk<R extends Rpc.Any> extends Data.TaggedClass("Chunk")<{
    * @stability unstable
    * @since 4.0.0
    */
-  static readonly Any = Schema.declare((u): u is Chunk<never> => isReply(u) && u._tag === "Chunk")
+  static readonly Any = Schema.declare((u): u is Chunk<Rpc.Any> => isReply(u) && u._tag === "Chunk")
 
   /**
    * Transformation between encoded chunk records and `Chunk` instances.

package/src/cluster/Sharding.ts

@@ -19,7 +19,7 @@ import type { Input } from "../Duration.ts"
 import * as Duration from "../Duration.ts"
 import * as Effect from "../Effect.ts"
 import * as Equal from "../Equal.ts"
-import type * as Exit from "../Exit.ts"
+import * as Exit from "../Exit.ts"
 import * as Fiber from "../Fiber.ts"
 import * as FiberMap from "../FiberMap.ts"
 import { constant, flow } from "../Function.ts"
@@ -281,6 +281,9 @@ const make = Effect.gen(function*() {
   // shards still held by this runner while their entities stop and their locks
   // are released
   const releasingShards = MutableHashSet.empty<ShardId>()
+  // runners that joined after the first assignment, kept out of the hash rings
+  // until the healthy set settles (see `runnerJoinDebounce`)
+  const pendingRunners = MutableHashSet.empty<Runner>()
   // The releasing gauge reports to the metric registry and attributes the
   // layer was built with.
   const updateReleasingShardsGauge = () =>
@@ -611,6 +614,13 @@ const make = Effect.gen(function*() {
           continue
         }
 
+        // While joins are pending the assignments are about to change, so take
+        // no new shards; otherwise a shard released for a joining runner could
+        // be taken here and handed off again. Publishing reopens the latch.
+        if (MutableHashSet.size(pendingRunners) > 0) {
+          continue
+        }
+
         // if a shard has been assigned to this runner, we acquire it
         const unacquiredShards = MutableHashSet.empty<ShardId>()
         for (const shardId of selfShards) {
@@ -635,13 +645,16 @@ const make = Effect.gen(function*() {
           Effect.ignore,
           Effect.timeoutOption(shardLockInterval)
         )
-        // A forced release can start while `acquire` is in flight, so re-check
-        // it here as well as before acquiring.
+        // A forced release or a pending join can begin while `acquire` is in
+        // flight, so re-check both. Shards locked meanwhile are released
+        // without running anything on them.
         const forcedReleasePending = forcedShardReleasePending()
+        const joinsPending = MutableHashSet.size(pendingRunners) > 0
         for (const shardId of acquired) {
           if (
             !shardLocksHealthyLatch.isOpen() ||
             forcedReleasePending ||
+            joinsPending ||
             MutableHashSet.has(releasingShards, shardId) ||
             !MutableHashSet.has(selfShards, shardId)
           ) {
@@ -1415,10 +1428,33 @@ const make = Effect.gen(function*() {
     ClusterMetrics.runnersHealthy.updateUnsafe(BigInt(1), Context.empty())
   }
 
+  // Kept outside the loop so a restart after a storage failure does not drop
+  // this state and publish pending joins early.
+  const hashRings = new Map<string, HashRing.HashRing<RunnerAddress>>()
+  let nextRunners = MutableHashMap.empty<Runner, boolean>()
+  const healthyRunners = MutableHashSet.empty<Runner>()
+  const joinDebounce = Duration.toMillis(Duration.fromInputUnsafe(config.runnerJoinDebounce))
+  // when the first pending join and the latest pending change were observed
+  let pendingSince = 0
+  let pendingChangedAt = 0
+  // the initial assignment never waits, even if this runner ends up with no shards
+  let assignmentsPublished = false
+  // stays set until the assignments are actually recomputed
+  let changed = false
+
+  const addToRings = (runner: Runner) => {
+    for (let i = 0; i < runner.groups.length; i++) {
+      const group = runner.groups[i]
+      let ring = hashRings.get(group)
+      if (!ring) {
+        ring = HashRing.make()
+        hashRings.set(group, ring)
+      }
+      HashRing.add(ring, runner.address, { weight: runner.weight })
+    }
+  }
+
   yield* Effect.gen(function*() {
-    const hashRings = new Map<string, HashRing.HashRing<RunnerAddress>>()
-    let nextRunners = MutableHashMap.empty<Runner, boolean>()
-    const healthyRunners = MutableHashSet.empty<Runner>()
     const withTimeout = Effect.timeout(Duration.seconds(5))
 
     while (true) {
@@ -1433,7 +1469,7 @@ const make = Effect.gen(function*() {
       }
 
       const runners = yield* withTimeout(runnerStorage.getRunners)
-      let changed = false
+      const now = clock.currentTimeMillisUnsafe()
       for (let i = 0; i < runners.length; i++) {
         const [runner, healthy] = runners[i]
         MutableHashMap.set(nextRunners, runner, healthy)
@@ -1445,31 +1481,55 @@ const make = Effect.gen(function*() {
           }
           continue
         }
-        changed = true
         MutableHashSet.add(healthyRunners, runner)
         MutableHashMap.remove(allRunners, runner)
-        for (let j = 0; j < runner.groups.length; j++) {
-          const group = runner.groups[j]
-          let ring = hashRings.get(group)
-          if (!ring) {
-            ring = HashRing.make()
-            hashRings.set(group, ring)
+        if (joinDebounce > 0 && assignmentsPublished) {
+          if (MutableHashSet.size(pendingRunners) === 0) {
+            pendingSince = now
           }
-          HashRing.add(ring, runner.address, { weight: runner.weight })
+          pendingChangedAt = now
+          MutableHashSet.add(pendingRunners, runner)
+          continue
         }
+        changed = true
+        addToRings(runner)
       }
 
       // Remove runners that are no longer present or healthy
       MutableHashMap.forEach(allRunners, (_, runner) => {
-        changed = true
         MutableHashMap.remove(allRunners, runner)
         MutableHashSet.remove(healthyRunners, runner)
         runFork(runnersService.onRunnerUnavailable(runner.address))
+        // A pending runner owns no shards, so its departure only restarts the
+        // quiet period instead of publishing the other joins mid-burst.
+        if (MutableHashSet.has(pendingRunners, runner)) {
+          MutableHashSet.remove(pendingRunners, runner)
+          pendingChangedAt = now
+          if (MutableHashSet.size(pendingRunners) === 0) {
+            // let the acquisition loop take the shards it was holding off on
+            activeShardsLatch.openUnsafe()
+          }
+          return
+        }
+        changed = true
         for (let i = 0; i < runner.groups.length; i++) {
           HashRing.remove(hashRings.get(runner.groups[i])!, runner.address)
         }
       })
 
+      // Publish pending joins once the healthy set has settled, the cap is
+      // reached, or the assignments are recomputed anyway.
+      if (
+        MutableHashSet.size(pendingRunners) > 0 &&
+        (changed || now - pendingChangedAt >= joinDebounce || now - pendingSince >= joinDebounce * 4)
+      ) {
+        changed = true
+        for (const runner of pendingRunners) {
+          addToRings(runner)
+        }
+        MutableHashSet.clear(pendingRunners)
+      }
+
       // swap allRunners and nextRunners
       const prevRunners = allRunners
       allRunners = nextRunners
@@ -1483,6 +1543,8 @@ const make = Effect.gen(function*() {
 
       // Recompute shard assignments if the set of healthy runners has changed.
       if (changed) {
+        changed = false
+        assignmentsPublished = true
         MutableHashSet.clear(selfShards)
         hashRings.forEach((ring, group) => {
           const newAssignments = HashRing.getShards(ring, config.shardsPerGroup)
@@ -1619,18 +1681,26 @@ const make = Effect.gen(function*() {
                   envelope as any
                 )
               })
-              if (!options.discard) {
-                const entry: ClientRequestEntry = {
-                  rpc: rpc as any,
-                  context: fiber.context,
-                  message
-                }
-                clientRequests.set(id, entry)
-                respond = makeClientRespond(entry, client.write)
-              } else {
+              if (options.message.discard === true) {
                 respond = clientRespondDiscard
+                // a discarded call is acknowledged once its message is sent
+                const requestId = options.message.id
+                return Effect.flatMap(
+                  sendOutgoing(message, true),
+                  () => client.write({ _tag: "Exit", clientId: 0, requestId, exit: Exit.void as any })
+                )
+              }
+              const entry: ClientRequestEntry = {
+                rpc: rpc as any,
+                context: fiber.context,
+                message
               }
-              return sendOutgoing(message, options.discard)
+              clientRequests.set(id, entry)
+              respond = makeClientRespond(entry, client.write)
+              // A failed send leaves no reply or interrupt to release the entry.
+              // Only drop the local bookkeeping, as the request may have been
+              // persisted.
+              return Effect.tapError(sendOutgoing(message, false), () => Effect.sync(() => clientRequests.delete(id)))
             }
             case "Ack": {
               const requestId = Snowflake.Snowflake(options.message.requestId)

package/src/cluster/ShardingConfig.ts

@@ -82,10 +82,12 @@ export class ShardingConfig extends Context.Service<ShardingConfig, {
   /**
    * Shard lock expiration duration.
    *
-   * With PostgreSQL advisory locks (PostgreSQL 14+), this also bounds how long
-   * a runner that stops refreshing, for example because its process is frozen,
+   * With PostgreSQL (14+) or MySQL advisory locks, this also bounds how long a
+   * runner that stops refreshing, for example because its process is frozen,
    * keeps its shards: the server ends its idle lock session after this
-   * duration, releasing the locks.
+   * duration, releasing the locks. On MySQL it is rounded up to whole
+   * seconds. Vitess ignores the MySQL session timeout, so behind Vitess the
+   * locks stay held until the runner's connection closes.
    */
   readonly shardLockExpiration: Duration.Input
   /**
@@ -165,6 +167,37 @@ export class ShardingConfig extends Context.Service<ShardingConfig, {
    * assignments.
    */
   readonly refreshAssignmentsInterval: Duration.Input
+  /**
+   * How long the healthy runners must stay unchanged before runners that
+   * joined are added to shard assignments. A burst of joins, such as a
+   * scale-up or a deployment with a large surge, is then published as one
+   * assignment and each shard is handed off once instead of once per join.
+   * In a rolling update that replaces one runner at a time, each departure is
+   * still published immediately, so shards still move at every step.
+   *
+   * Only joins wait. The initial assignment, departures and unhealthy runners
+   * are published immediately, together with any pending joins. A pending
+   * runner that leaves has no shards to move, so it only restarts the quiet
+   * period.
+   *
+   * While joins are pending, shards keep running where they are, the new
+   * runners stay idle and no runner takes shards it does not already hold.
+   * Runners publish on their own polls, so a shard released by one runner can
+   * stay unlocked until its new owner publishes, usually within two
+   * `refreshAssignmentsInterval`s. A runner that does not observe the joins,
+   * for example because it cannot read membership, can still take shards from
+   * its outdated assignment and hand them off again, as with `0`.
+   *
+   * Pending joins are published at most four times this duration after the
+   * first one, even if runners keep joining. The quiet period is checked once
+   * per `refreshAssignmentsInterval`, so the worst case delay is four times
+   * this duration plus one interval, and values shorter than the interval
+   * behave like a single quiet poll.
+   *
+   * Defaults to `0`, which publishes every change immediately. Leave it at
+   * `0` for scale-ups driven by load, where idle new runners are costly.
+   */
+  readonly runnerJoinDebounce: Duration.Input
   /**
    * The interval to retry a send if EntityNotAssignedToRunner is returned.
    */
@@ -213,6 +246,7 @@ export const defaults: ShardingConfig["Service"] = {
   entityReplyPollInterval: Duration.millis(200),
   sendRetryInterval: Duration.millis(100),
   refreshAssignmentsInterval: Duration.seconds(3),
+  runnerJoinDebounce: Duration.zero,
   runnerHealthCheckInterval: Duration.minutes(1),
   simulateRemoteSerialization: true
 }
@@ -371,6 +405,10 @@ export const config: Config.Config<ShardingConfig["Service"]> = Config.all({
     Config.withDefault(defaults.refreshAssignmentsInterval)
     // Config.withDescription("The interval at which to refresh shard assignments.")
   ),
+  runnerJoinDebounce: Config.Duration("runnerJoinDebounce").pipe(
+    Config.withDefault(defaults.runnerJoinDebounce)
+    // Config.withDescription("How long the healthy runners must stay unchanged before joining runners are assigned shards.")
+  ),
   runnerHealthCheckInterval: Config.Duration("runnerHealthCheckInterval").pipe(
     Config.withDefault(defaults.runnerHealthCheckInterval)
     // Config.withDescription("The interval at which to check for unhealthy runners and report them.")

package/src/cluster/SingleRunner.ts

@@ -13,7 +13,7 @@
  */
 import * as Layer from "effect/Layer"
 import type { ConfigError } from "../Config.ts"
-import type * as Crypto from "../Crypto.ts"
+import type * as Digest from "../crypto/Digest.ts"
 import type * as SqlClient from "../sql/SqlClient.ts"
 import type * as MessageStorage from "./MessageStorage.ts"
 import * as RunnerHealth from "./RunnerHealth.ts"
@@ -44,7 +44,7 @@ import * as SqlRunnerStorage from "./SqlRunnerStorage.ts"
  * **Gotchas**
  *
  * - Even when `runnerStorage` is `"memory"`, message storage remains
- *   SQL-backed, so callers must still provide `SqlClient` and `Crypto.Crypto`
+ *   SQL-backed, so callers must still provide `SqlClient` and `Digest.Digest`
  *   (used to hash over-length message deduplication keys).
  * - Runner communication and runner health are no-op services, so this layer is
  *   for single-process use rather than multi-runner coordination.
@@ -66,7 +66,7 @@ export const layer = (options?: {
   | Runners.Runners
   | MessageStorage.MessageStorage,
   ConfigError,
-  SqlClient.SqlClient | Crypto.Crypto
+  SqlClient.SqlClient | Digest.Digest
 > =>
   Sharding.layer.pipe(
     Layer.provideMerge(Runners.layerNoop),