effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/unstable/cluster/ShardingConfig.js

@@ -1,18 +1,39 @@
 /**
- * The `ShardingConfig` module defines the configuration used by a cluster
- * runner to participate in Effect Cluster sharding. It describes how a runner is
- * addressed by other runners, which shard groups it can host, how many shards
- * are assigned per group, and the timing settings used for locks, assignment
- * refreshes, health checks, entity lifecycle, and message polling.
- *
- * Use this module when wiring a sharded application locally with
- * {@link layer}, loading deployment settings from environment variables with
- * {@link layerFromEnv}, or overriding selected defaults for tests and
- * single-node development. In production, keep cluster-wide values such as
- * `shardsPerGroup` and shard groups consistent across runners, choose stable
- * externally reachable runner addresses, and tune lock expiration and refresh
- * intervals to match the storage backend and shutdown behavior of the
- * deployment platform.
+ * The `ShardingConfig` module describes how an Effect Cluster runner joins and
+ * participates in sharding. It combines the runner network identity, shard group
+ * membership, shard-count and weight settings, storage-lock timing, entity
+ * mailbox and lifecycle limits, and polling intervals used by the local runner.
+ *
+ * **Mental model**
+ *
+ * - {@link ShardingConfig} is provided as a service so cluster components read
+ *   one consistent set of sharding settings.
+ * - {@link defaults} is the local-development baseline; {@link layer} overlays
+ *   explicit values, and {@link layerFromEnv} loads constant-case environment
+ *   variables before applying optional overrides.
+ * - `runnerAddress` is the externally reachable address advertised to other
+ *   runners; `runnerListenAddress` can differ when the process binds a
+ *   different interface.
+ * - `availableShardGroups`, `assignedShardGroups`, `shardsPerGroup`, and
+ *   `runnerShardWeight` decide which shards a runner may own and how assignment
+ *   is balanced.
+ *
+ * **Common tasks**
+ *
+ * - Provide default local configuration with {@link layerDefaults}.
+ * - Override selected fields in code with {@link layer}.
+ * - Load deployment configuration from the environment with
+ *   {@link configFromEnv} or {@link layerFromEnv}.
+ * - Normalize configured shard groups with {@link shardGroupConfig}.
+ *
+ * **Gotchas**
+ *
+ * - Keep cluster-wide values such as `availableShardGroups` and
+ *   `shardsPerGroup` consistent for runners sharing the same storage backend.
+ * - Use stable, reachable `runnerAddress` values; client-only nodes should use
+ *   `Option.none()` for `runnerAddress`.
+ * - Tune lock expiration, refresh intervals, and termination timeouts together
+ *   so normal shutdown does not look like runner failure.
  *
  * @since 4.0.0
  */
@@ -70,6 +91,29 @@ export const defaults = {
  * Creates a `ShardingConfig` layer by merging the provided partial options over
  * `defaults`.
  *
+ * **When to use**
+ *
+ * Use when wiring a cluster runner with explicit `ShardingConfig` values,
+ * especially in tests, local development, or code paths where configuration
+ * should be provided programmatically instead of loaded from environment
+ * variables.
+ *
+ * **Details**
+ *
+ * The merge is shallow: omitted fields use `defaults`, and provided fields
+ * replace the corresponding default value.
+ *
+ * **Gotchas**
+ *
+ * This layer only merges and provides configuration; it does not check that
+ * cluster-wide settings are consistent across runners. Keep values such as
+ * `shardsPerGroup` and `availableShardGroups` aligned for runners that should
+ * share shard assignments.
+ *
+ * @see {@link defaults} for the values used when an option is omitted
+ * @see {@link layerDefaults} for a layer with no overrides
+ * @see {@link layerFromEnv} for loading configuration from environment variables before applying explicit overrides
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -85,10 +129,10 @@ export const layer = options => Layer.succeed(ShardingConfig)({
  */
 export const layerDefaults = /*#__PURE__*/layer();
 /**
- * Config descriptor for loading `ShardingConfig` values, applying the same
+ * Describes how to load `ShardingConfig` values, applying the same
  * defaults used by the in-memory `defaults` object.
  *
- * @category Config
+ * @category configuration
  * @since 4.0.0
  */
 export const config = /*#__PURE__*/Config.all({
@@ -169,7 +213,7 @@ export const config = /*#__PURE__*/Config.all({
  * Effect that loads `ShardingConfig` from environment variables using the
  * constant-case config provider.
  *
- * @category Config
+ * @category configuration
  * @since 4.0.0
  */
 export const configFromEnv = /*#__PURE__*/config.pipe(/*#__PURE__*/Effect.provideService(ConfigProvider.ConfigProvider, /*#__PURE__*/ConfigProvider.fromEnv().pipe(ConfigProvider.constantCase)));

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

@@ -1 +1 @@
-{"version":3,"file":"ShardingConfig.js","names":["Config","ConfigProvider","Context","Duration","Effect","Layer","Option","Schema","RunnerAddress","ShardingConfig","Service","defaultRunnerAddress","make","host","port","defaults","runnerAddress","some","runnerListenAddress","none","runnerShardWeight","shardsPerGroup","availableShardGroups","assignedShardGroups","preemptiveShutdown","shardLockRefreshInterval","seconds","shardLockExpiration","shardLockDisableAdvisory","entityMailboxCapacity","entityMaxIdleTime","minutes","entityRegistrationTimeout","entityTerminationTimeout","entityMessagePollInterval","entityReplyPollInterval","millis","sendRetryInterval","refreshAssignmentsInterval","runnerHealthCheckInterval","simulateRemoteSerialization","layer","options","succeed","layerDefaults","config","all","string","pipe","withDefault","int","map","option","schema","Array","String","duration","boolean","configFromEnv","provideService","fromEnv","constantCase","layerFromEnv","effect","shardGroupConfig","available","Set","slice","sort","assigned","forEach","group","includes","add"],"sources":["../../../src/unstable/cluster/ShardingConfig.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;AAkBA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,cAAc,MAAM,yBAAyB;AACzD,OAAO,KAAKC,OAAO,MAAM,kBAAkB;AAC3C,OAAO,KAAKC,QAAQ,MAAM,mBAAmB;AAC7C,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AACvC,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AACzC,SAASC,aAAa,QAAQ,oBAAoB;AAElD;;;;;;AAMA,OAAM,MAAOC,cAAe,sBAAQP,OAAO,CAACQ,OAAO,EA6G/C,CAAC,+BAA+B,CAAC;AAErC,MAAMC,oBAAoB,gBAAGH,aAAa,CAACI,IAAI,CAAC;EAAEC,IAAI,EAAE,WAAW;EAAEC,IAAI,EAAE;AAAK,CAAE,CAAC;AAEnF;;;;;;;;AAQA,OAAO,MAAMC,QAAQ,GAA8B;EACjDC,aAAa,eAAEV,MAAM,CAACW,IAAI,CAACN,oBAAoB,CAAC;EAChDO,mBAAmB,eAAEZ,MAAM,CAACa,IAAI,EAAE;EAClCC,iBAAiB,EAAE,CAAC;EACpBC,cAAc,EAAE,GAAG;EACnBC,oBAAoB,EAAE,CAAC,SAAS,CAAC;EACjCC,mBAAmB,EAAE,CAAC,SAAS,CAAC;EAChCC,kBAAkB,EAAE,IAAI;EACxBC,wBAAwB,eAAEtB,QAAQ,CAACuB,OAAO,CAAC,EAAE,CAAC;EAC9CC,mBAAmB,eAAExB,QAAQ,CAACuB,OAAO,CAAC,EAAE,CAAC;EACzCE,wBAAwB,EAAE,KAAK;EAC/BC,qBAAqB,EAAE,IAAI;EAC3BC,iBAAiB,eAAE3B,QAAQ,CAAC4B,OAAO,CAAC,CAAC,CAAC;EACtCC,yBAAyB,eAAE7B,QAAQ,CAAC4B,OAAO,CAAC,CAAC,CAAC;EAC9CE,wBAAwB,eAAE9B,QAAQ,CAACuB,OAAO,CAAC,EAAE,CAAC;EAC9CQ,yBAAyB,eAAE/B,QAAQ,CAACuB,OAAO,CAAC,EAAE,CAAC;EAC/CS,uBAAuB,eAAEhC,QAAQ,CAACiC,MAAM,CAAC,GAAG,CAAC;EAC7CC,iBAAiB,eAAElC,QAAQ,CAACiC,MAAM,CAAC,GAAG,CAAC;EACvCE,0BAA0B,eAAEnC,QAAQ,CAACuB,OAAO,CAAC,CAAC,CAAC;EAC/Ca,yBAAyB,eAAEpC,QAAQ,CAAC4B,OAAO,CAAC,CAAC,CAAC;EAC9CS,2BAA2B,EAAE;CAC9B;AAED;;;;;;;AAOA,OAAO,MAAMC,KAAK,GAAIC,OAA4C,IAChErC,KAAK,CAACsC,OAAO,CAAClC,cAAc,CAAC,CAAC;EAAE,GAAGM,QAAQ;EAAE,GAAG2B;AAAO,CAAE,CAAC;AAE5D;;;;;;AAMA,OAAO,MAAME,aAAa,gBAAgCH,KAAK,EAAE;AAEjE;;;;;;;AAOA,OAAO,MAAMI,MAAM,gBAA6C7C,MAAM,CAAC8C,GAAG,CAAC;EACzE9B,aAAa,eAAEhB,MAAM,CAAC8C,GAAG,CAAC;IACxBjC,IAAI,EAAEb,MAAM,CAAC+C,MAAM,CAAC,MAAM,CAAC,CAACC,IAAI,CAC9BhD,MAAM,CAACiD,WAAW,CAACtC,oBAAoB,CAACE,IAAI;IAC5C;KACD;IACDC,IAAI,EAAEd,MAAM,CAACkD,GAAG,CAAC,MAAM,CAAC,CAACF,IAAI,CAC3BhD,MAAM,CAACiD,WAAW,CAACtC,oBAAoB,CAACG,IAAI;IAC5C;;GAEH,CAAC,CAACkC,IAAI,cAAChD,MAAM,CAACmD,GAAG,CAAET,OAAO,IAAKlC,aAAa,CAACI,IAAI,CAAC8B,OAAO,CAAC,CAAC,EAAE1C,MAAM,CAACoD,MAAM,CAAC;EAC5ElC,mBAAmB,eAAElB,MAAM,CAAC8C,GAAG,CAAC;IAC9BjC,IAAI,EAAEb,MAAM,CAAC+C,MAAM,CAAC,YAAY,CAAC;IACjC;IACAjC,IAAI,EAAEd,MAAM,CAACkD,GAAG,CAAC,YAAY,CAAC,CAACF,IAAI,CACjChD,MAAM,CAACiD,WAAW,CAACtC,oBAAoB,CAACG,IAAI;IAC5C;;GAEH,CAAC,CAACkC,IAAI,cAAChD,MAAM,CAACmD,GAAG,CAAET,OAAO,IAAKlC,aAAa,CAACI,IAAI,CAAC8B,OAAO,CAAC,CAAC,EAAE1C,MAAM,CAACoD,MAAM,CAAC;EAC5EhC,iBAAiB,eAAEpB,MAAM,CAACkD,GAAG,CAAC,mBAAmB,CAAC,CAACF,IAAI,cACrDhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACK,iBAAiB;EAC7C;GACD;EACDE,oBAAoB,eAAEtB,MAAM,CAACqD,MAAM,CAAC9C,MAAM,CAAC+C,KAAK,CAAC/C,MAAM,CAACgD,MAAM,CAAC,EAAE,sBAAsB,CAAC,CAACP,IAAI,cAC3FhD,MAAM,CAACiD,WAAW,CAAC,CAAC,SAAS,CAAC;EAC9B;GACD;EACD1B,mBAAmB,eAAEvB,MAAM,CAACqD,MAAM,CAAC9C,MAAM,CAAC+C,KAAK,CAAC/C,MAAM,CAACgD,MAAM,CAAC,EAAE,aAAa,CAAC,CAACP,IAAI,cACjFhD,MAAM,CAACiD,WAAW,CAAC,CAAC,SAAS,CAAC;EAC9B;GACD;EACD5B,cAAc,eAAErB,MAAM,CAACkD,GAAG,CAAC,gBAAgB,CAAC,CAACF,IAAI,cAC/ChD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACM,cAAc;EAC1C;GACD;EACDI,wBAAwB,eAAEzB,MAAM,CAACwD,QAAQ,CAAC,0BAA0B,CAAC,CAACR,IAAI,cACxEhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACU,wBAAwB;EACpD;GACD;EACDE,mBAAmB,eAAE3B,MAAM,CAACwD,QAAQ,CAAC,qBAAqB,CAAC,CAACR,IAAI,cAC9DhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACY,mBAAmB;EAC/C;GACD;EACDC,wBAAwB,eAAE5B,MAAM,CAACyD,OAAO,CAAC,0BAA0B,CAAC,CAACT,IAAI,cACvEhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACa,wBAAwB;EACpD;GACD;EACDJ,kBAAkB,eAAExB,MAAM,CAACyD,OAAO,CAAC,oBAAoB,CAAC,CAACT,IAAI,cAC3DhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACS,kBAAkB;EAC9C;GACD;EACDK,qBAAqB,eAAE7B,MAAM,CAACkD,GAAG,CAAC,uBAAuB,CAAC,CAACF,IAAI,cAC7DhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACc,qBAAqB;EACjD;GACD;EACDC,iBAAiB,eAAE9B,MAAM,CAACwD,QAAQ,CAAC,mBAAmB,CAAC,CAACR,IAAI,cAC1DhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACe,iBAAiB;EAC7C;EACA;EACA;GACD;EACDE,yBAAyB,eAAEhC,MAAM,CAACwD,QAAQ,CAAC,2BAA2B,CAAC,CAACR,IAAI,cAC1EhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACiB,yBAAyB;EACrD;GACD;EACDC,wBAAwB,eAAEjC,MAAM,CAACwD,QAAQ,CAAC,0BAA0B,CAAC,CAACR,IAAI,cACxEhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACkB,wBAAwB;EACpD;GACD;EACDC,yBAAyB,eAAElC,MAAM,CAACwD,QAAQ,CAAC,2BAA2B,CAAC,CAACR,IAAI,cAC1EhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACmB,yBAAyB;EACrD;GACD;EACDC,uBAAuB,eAAEnC,MAAM,CAACwD,QAAQ,CAAC,yBAAyB,CAAC,CAACR,IAAI,cACtEhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACoB,uBAAuB;EACnD;GACD;EACDE,iBAAiB,eAAErC,MAAM,CAACwD,QAAQ,CAAC,mBAAmB,CAAC,CAACR,IAAI,cAC1DhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACsB,iBAAiB;EAC7C;GACD;EACDC,0BAA0B,eAAEtC,MAAM,CAACwD,QAAQ,CAAC,4BAA4B,CAAC,CAACR,IAAI,cAC5EhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACuB,0BAA0B;EACtD;GACD;EACDC,yBAAyB,eAAEvC,MAAM,CAACwD,QAAQ,CAAC,2BAA2B,CAAC,CAACR,IAAI,cAC1EhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACwB,yBAAyB;EACrD;GACD;EACD;EACAC,2BAA2B,eAAExC,MAAM,CAACyD,OAAO,CAAC,6BAA6B,CAAC,CAACT,IAAI,cAC7EhD,MAAM,CAACiD,WAAW,CAAClC,QAAQ,CAACyB,2BAA2B;EACvD;;CAEH,CAAC;AAEF;;;;;;;AAOA,OAAO,MAAMkB,aAAa,gBAAGb,MAAM,CAACG,IAAI,cACtC5C,MAAM,CAACuD,cAAc,CACnB1D,cAAc,CAACA,cAAc,eAC7BA,cAAc,CAAC2D,OAAO,EAAE,CAACZ,IAAI,CAC3B/C,cAAc,CAAC4D,YAAY,CAC5B,CACF,CACF;AAED;;;;;;;AAOA,OAAO,MAAMC,YAAY,GAAIpB,OAAwD,IAInFrC,KAAK,CAAC0D,MAAM,CAACtD,cAAc,CAAC,CAC1BiC,OAAO,GAAGtC,MAAM,CAAC+C,GAAG,CAACO,aAAa,EAAGb,MAAM,KAAM;EAAE,GAAGA,MAAM;EAAE,GAAGH;AAAO,CAAE,CAAC,CAAC,GAAGgB,aAAa,CAC7F;AAEH;;;;;;;AAOA,OAAO,MAAMM,gBAAgB,GAAInB,MAAiC,IAG9D;EACF,MAAMoB,SAAS,GAAG,IAAIC,GAAG,CAACrB,MAAM,CAACvB,oBAAoB,CAAC6C,KAAK,EAAE,CAACC,IAAI,EAAE,CAAC;EACrE,MAAMC,QAAQ,GAAG,IAAIH,GAAG,EAAU;EAClCD,SAAS,CAACK,OAAO,CAAEC,KAAK,IAAI;IAC1B,IAAI1B,MAAM,CAACtB,mBAAmB,CAACiD,QAAQ,CAACD,KAAK,CAAC,EAAE;MAC9CF,QAAQ,CAACI,GAAG,CAACF,KAAK,CAAC;IACrB;EACF,CAAC,CAAC;EACF,OAAO;IAAEN,SAAS;IAAEI;EAAQ,CAAE;AAChC,CAAC","ignoreList":[]}
+{"version":3,"file":"ShardingConfig.js","names":["Config","ConfigProvider","Context","Duration","Effect","Layer","Option","Schema","RunnerAddress","ShardingConfig","Service","defaultRunnerAddress","make","host","port","defaults","runnerAddress","some","runnerListenAddress","none","runnerShardWeight","shardsPerGroup","availableShardGroups","assignedShardGroups","preemptiveShutdown","shardLockRefreshInterval","seconds","shardLockExpiration","shardLockDisableAdvisory","entityMailboxCapacity","entityMaxIdleTime","minutes","entityRegistrationTimeout","entityTerminationTimeout","entityMessagePollInterval","entityReplyPollInterval","millis","sendRetryInterval","refreshAssignmentsInterval","runnerHealthCheckInterval","simulateRemoteSerialization","layer","options","succeed","layerDefaults","config","all","string","pipe","withDefault","int","map","option","schema","Array","String","duration","boolean","configFromEnv","provideService","fromEnv","constantCase","layerFromEnv","effect","shardGroupConfig","available","Set","slice","sort","assigned","forEach","group","includes","add"],"sources":["../../../src/unstable/cluster/ShardingConfig.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

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

@@ -1,17 +1,31 @@
 /**
- * The `ShardingRegistrationEvent` module defines the events emitted by
- * `Sharding` when the local runner registers entity handlers or singleton
- * workloads. These events are useful for observing the set of capabilities a
- * runner has made available, coordinating startup hooks, and writing tests or
- * integrations that need to react when registrations are complete.
+ * The `ShardingRegistrationEvent` module models the live notifications emitted
+ * by `Sharding` when the local runner registers an entity handler or singleton.
+ * Consumers can use these events to wait for registrations during startup,
+ * inspect which capabilities a runner made available, or assert registration
+ * behavior in tests.
  *
- * Registration events describe local registration, not shard ownership or
- * execution. A runner may register an entity or singleton before it owns the
- * shard that will run it, and the events are in-memory notifications from the
- * `Sharding` service rather than persisted cluster state. For persisted
- * messages, treat registration as the point where the handler is available to
- * the runner; it does not imply that existing storage work has already been
- * read or processed.
+ * **Mental model**
+ *
+ * Registration is local capability discovery. An `EntityRegistered` event means
+ * this runner has installed handlers for an entity type; a `SingletonRegistered`
+ * event carries the `SingletonAddress` computed for the singleton name and shard
+ * group. Neither event means the runner currently owns the relevant shard or has
+ * started processing stored messages.
+ *
+ * **Common tasks**
+ *
+ * - Consume `Sharding.getRegistrationEvents` in tests or startup coordination
+ * - Match on entity and singleton registrations with the generated `match`
+ *   helper
+ * - Record registered entity types and singleton addresses for diagnostics
+ *
+ * **Gotchas**
+ *
+ * - Events are live in-memory notifications; they are not stored or replayed for
+ *   later subscribers
+ * - Shard acquisition, singleton execution, and persisted mailbox polling happen
+ *   after registration and may move as runner membership changes
  *
  * @since 4.0.0
  */
@@ -47,8 +61,7 @@ export interface SingletonRegistered {
     readonly address: SingletonAddress;
 }
 /**
- * Generated helpers for pattern matching and constructing sharding registration
- * events.
+ * Constructors and matchers for sharding registration events.
  *
  * @category pattern matching
  * @since 4.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"ShardingRegistrationEvent.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ShardingRegistrationEvent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,IAAI,MAAM,eAAe,CAAA;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC,gBAAgB,GAChB,mBAAmB,CAAA;AAEvB;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;CACnC;AAED;;;;;;GAMG;AACH,eAAO,MAQG,KAAK;;;;;;;;;;AACb;;;;;GAKG;AACH,gBAAgB;AAChB;;;;;GAKG;AACH,mBAAmB,8DAC2B,CAAA"}
+{"version":3,"file":"ShardingRegistrationEvent.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/ShardingRegistrationEvent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,IAAI,MAAM,eAAe,CAAA;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC,gBAAgB,GAChB,mBAAmB,CAAA;AAEvB;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAQG,KAAK;;;;;;;;;;AACb;;;;;GAKG;AACH,gBAAgB;AAChB;;;;;GAKG;AACH,mBAAmB,8DAC2B,CAAA"}

package/dist/unstable/cluster/ShardingRegistrationEvent.js

@@ -1,24 +1,37 @@
 /**
- * The `ShardingRegistrationEvent` module defines the events emitted by
- * `Sharding` when the local runner registers entity handlers or singleton
- * workloads. These events are useful for observing the set of capabilities a
- * runner has made available, coordinating startup hooks, and writing tests or
- * integrations that need to react when registrations are complete.
- *
- * Registration events describe local registration, not shard ownership or
- * execution. A runner may register an entity or singleton before it owns the
- * shard that will run it, and the events are in-memory notifications from the
- * `Sharding` service rather than persisted cluster state. For persisted
- * messages, treat registration as the point where the handler is available to
- * the runner; it does not imply that existing storage work has already been
- * read or processed.
+ * The `ShardingRegistrationEvent` module models the live notifications emitted
+ * by `Sharding` when the local runner registers an entity handler or singleton.
+ * Consumers can use these events to wait for registrations during startup,
+ * inspect which capabilities a runner made available, or assert registration
+ * behavior in tests.
+ *
+ * **Mental model**
+ *
+ * Registration is local capability discovery. An `EntityRegistered` event means
+ * this runner has installed handlers for an entity type; a `SingletonRegistered`
+ * event carries the `SingletonAddress` computed for the singleton name and shard
+ * group. Neither event means the runner currently owns the relevant shard or has
+ * started processing stored messages.
+ *
+ * **Common tasks**
+ *
+ * - Consume `Sharding.getRegistrationEvents` in tests or startup coordination
+ * - Match on entity and singleton registrations with the generated `match`
+ *   helper
+ * - Record registered entity types and singleton addresses for diagnostics
+ *
+ * **Gotchas**
+ *
+ * - Events are live in-memory notifications; they are not stored or replayed for
+ *   later subscribers
+ * - Shard acquisition, singleton execution, and persisted mailbox polling happen
+ *   after registration and may move as runner membership changes
  *
  * @since 4.0.0
  */
 import * as Data from "../../Data.js";
 /**
- * Generated helpers for pattern matching and constructing sharding registration
- * events.
+ * Constructors and matchers for sharding registration events.
  *
  * @category pattern matching
  * @since 4.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"ShardingRegistrationEvent.js","names":["Data","$match","match","EntityRegistered","SingletonRegistered","taggedEnum"],"sources":["../../../src/unstable/cluster/ShardingRegistrationEvent.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBA,OAAO,KAAKA,IAAI,MAAM,eAAe;AAqCrC;;;;;;;AAOA,OAAO,MAAM;EACX;;;;;;;EAOAC,MAAM,EAAEC,KAAK;EACb;;;;;;EAMAC,gBAAgB;EAChB;;;;;;EAMAC;AAAmB,CACpB,gBAAGJ,IAAI,CAACK,UAAU,EAA6B","ignoreList":[]}
+{"version":3,"file":"ShardingRegistrationEvent.js","names":["Data","$match","match","EntityRegistered","SingletonRegistered","taggedEnum"],"sources":["../../../src/unstable/cluster/ShardingRegistrationEvent.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,OAAO,KAAKA,IAAI,MAAM,eAAe;AAqCrC;;;;;;AAMA,OAAO,MAAM;EACX;;;;;;;EAOAC,MAAM,EAAEC,KAAK;EACb;;;;;;EAMAC,gBAAgB;EAChB;;;;;;EAMAC;AAAmB,CACpB,gBAAGJ,IAAI,CAACK,UAAU,EAA6B","ignoreList":[]}

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

@@ -31,9 +31,34 @@ import * as Runners from "./Runners.ts";
 import * as Sharding from "./Sharding.ts";
 import * as ShardingConfig from "./ShardingConfig.ts";
 /**
- * A sql backed single-node cluster, that can be used for running durable
+ * Provides a SQL-backed single-node cluster for running durable
  * entities and workflows.
  *
+ * **When to use**
+ *
+ * Use to run durable cluster entities and workflows in a local, embedded, or
+ * small single-node process while keeping mailbox and reply state in SQL.
+ *
+ * **Details**
+ *
+ * The layer provides `Sharding`, `Runners`, and `MessageStorage`. It loads
+ * `ShardingConfig` from environment variables and overlays
+ * `options.shardingConfig` when provided. Message storage is always SQL-backed;
+ * runner storage is SQL-backed by default and switches to in-memory storage
+ * when `runnerStorage` is set to `"memory"`.
+ *
+ * **Gotchas**
+ *
+ * - Even when `runnerStorage` is `"memory"`, message storage remains
+ *   SQL-backed, so callers must still provide `SqlClient`.
+ * - Runner communication and runner health are no-op services, so this layer is
+ *   for single-process use rather than multi-runner coordination.
+ *
+ * @see {@link ShardingConfig.layerFromEnv} for loading environment configuration before applying `shardingConfig` overrides
+ * @see {@link SqlMessageStorage.layer} for the SQL-backed message storage that this layer provides
+ * @see {@link SqlRunnerStorage.layer} for the default SQL-backed runner storage selected when `runnerStorage` is omitted or `"sql"`
+ * @see {@link RunnerStorage.layerMemory} for the in-memory runner storage selected by `runnerStorage: "memory"`
+ *
  * @category layers
  * @since 4.0.0
  */

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

@@ -1 +1 @@
-{"version":3,"file":"SingleRunner.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/SingleRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,KAAK,SAAS,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAE1D,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAIrD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAAI,UAAU;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACvF,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAA;CACtD,KAAG,KAAK,CAAC,KAAK,CACX,QAAQ,CAAC,QAAQ,GACjB,OAAO,CAAC,OAAO,GACf,cAAc,CAAC,cAAc,EAC/B,WAAW,EACX,SAAS,CAAC,SAAS,CAUlB,CAAA"}
+{"version":3,"file":"SingleRunner.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/SingleRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,KAAK,SAAS,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAE1D,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,KAAK,GAAI,UAAU;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACvF,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAA;CACtD,KAAG,KAAK,CAAC,KAAK,CACX,QAAQ,CAAC,QAAQ,GACjB,OAAO,CAAC,OAAO,GACf,cAAc,CAAC,cAAc,EAC/B,WAAW,EACX,SAAS,CAAC,SAAS,CAUlB,CAAA"}

package/dist/unstable/cluster/SingleRunner.js

@@ -32,9 +32,34 @@ import * as ShardingConfig from "./ShardingConfig.js";
 import * as SqlMessageStorage from "./SqlMessageStorage.js";
 import * as SqlRunnerStorage from "./SqlRunnerStorage.js";
 /**
- * A sql backed single-node cluster, that can be used for running durable
+ * Provides a SQL-backed single-node cluster for running durable
  * entities and workflows.
  *
+ * **When to use**
+ *
+ * Use to run durable cluster entities and workflows in a local, embedded, or
+ * small single-node process while keeping mailbox and reply state in SQL.
+ *
+ * **Details**
+ *
+ * The layer provides `Sharding`, `Runners`, and `MessageStorage`. It loads
+ * `ShardingConfig` from environment variables and overlays
+ * `options.shardingConfig` when provided. Message storage is always SQL-backed;
+ * runner storage is SQL-backed by default and switches to in-memory storage
+ * when `runnerStorage` is set to `"memory"`.
+ *
+ * **Gotchas**
+ *
+ * - Even when `runnerStorage` is `"memory"`, message storage remains
+ *   SQL-backed, so callers must still provide `SqlClient`.
+ * - Runner communication and runner health are no-op services, so this layer is
+ *   for single-process use rather than multi-runner coordination.
+ *
+ * @see {@link ShardingConfig.layerFromEnv} for loading environment configuration before applying `shardingConfig` overrides
+ * @see {@link SqlMessageStorage.layer} for the SQL-backed message storage that this layer provides
+ * @see {@link SqlRunnerStorage.layer} for the default SQL-backed runner storage selected when `runnerStorage` is omitted or `"sql"`
+ * @see {@link RunnerStorage.layerMemory} for the in-memory runner storage selected by `runnerStorage: "memory"`
+ *
  * @category layers
  * @since 4.0.0
  */

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

@@ -1 +1 @@
-{"version":3,"file":"SingleRunner.js","names":["Layer","RunnerHealth","Runners","RunnerStorage","Sharding","ShardingConfig","SqlMessageStorage","SqlRunnerStorage","layer","options","pipe","provideMerge","layerNoop","provide","runnerStorage","layerMemory","orDie","layerFromEnv","shardingConfig"],"sources":["../../../src/unstable/cluster/SingleRunner.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,KAAKA,KAAK,MAAM,cAAc;AAIrC,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AACjD,OAAO,KAAKC,OAAO,MAAM,cAAc;AACvC,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AACnD,OAAO,KAAKC,QAAQ,MAAM,eAAe;AACzC,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AACrD,OAAO,KAAKC,iBAAiB,MAAM,wBAAwB;AAC3D,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;;;;;AAOA,OAAO,MAAMC,KAAK,GAAIC,OAGrB,IAOCL,QAAQ,CAACI,KAAK,CAACE,IAAI,CACjBV,KAAK,CAACW,YAAY,CAACT,OAAO,CAACU,SAAS,CAAC,EACrCZ,KAAK,CAACW,YAAY,CAACL,iBAAiB,CAACE,KAAK,CAAC,EAC3CR,KAAK,CAACa,OAAO,CAAC,CACZJ,OAAO,EAAEK,aAAa,KAAK,QAAQ,GAAGX,aAAa,CAACY,WAAW,GAAGf,KAAK,CAACgB,KAAK,CAACT,gBAAgB,CAACC,KAAK,CAAC,EACrGP,YAAY,CAACW,SAAS,CACvB,CAAC,EACFZ,KAAK,CAACa,OAAO,CAACR,cAAc,CAACY,YAAY,CAACR,OAAO,EAAES,cAAc,CAAC,CAAC,CACpE","ignoreList":[]}
+{"version":3,"file":"SingleRunner.js","names":["Layer","RunnerHealth","Runners","RunnerStorage","Sharding","ShardingConfig","SqlMessageStorage","SqlRunnerStorage","layer","options","pipe","provideMerge","layerNoop","provide","runnerStorage","layerMemory","orDie","layerFromEnv","shardingConfig"],"sources":["../../../src/unstable/cluster/SingleRunner.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,KAAKA,KAAK,MAAM,cAAc;AAIrC,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AACjD,OAAO,KAAKC,OAAO,MAAM,cAAc;AACvC,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AACnD,OAAO,KAAKC,QAAQ,MAAM,eAAe;AACzC,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AACrD,OAAO,KAAKC,iBAAiB,MAAM,wBAAwB;AAC3D,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,OAAO,MAAMC,KAAK,GAAIC,OAGrB,IAOCL,QAAQ,CAACI,KAAK,CAACE,IAAI,CACjBV,KAAK,CAACW,YAAY,CAACT,OAAO,CAACU,SAAS,CAAC,EACrCZ,KAAK,CAACW,YAAY,CAACL,iBAAiB,CAACE,KAAK,CAAC,EAC3CR,KAAK,CAACa,OAAO,CAAC,CACZJ,OAAO,EAAEK,aAAa,KAAK,QAAQ,GAAGX,aAAa,CAACY,WAAW,GAAGf,KAAK,CAACgB,KAAK,CAACT,gBAAgB,CAACC,KAAK,CAAC,EACrGP,YAAY,CAACW,SAAS,CACvB,CAAC,EACFZ,KAAK,CAACa,OAAO,CAACR,cAAc,CAACY,YAAY,CAACR,OAAO,EAAES,cAAc,CAAC,CAAC,CACpE","ignoreList":[]}

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

@@ -1,14 +1,33 @@
 /**
- * The `Singleton` module provides a small helper for registering effects that
- * should run once across an Effect cluster. A singleton is coordinated through
- * `Sharding`, which assigns ownership to one node at a time and can move that
- * ownership when nodes leave or fail.
+ * Register effects that should have one active owner in an Effect cluster.
  *
- * Use singletons for cluster-wide background work such as schedulers, polling
- * loops, maintenance jobs, or consumers that must not have one instance per
- * process. Because ownership can change during failover, the registered effect
- * should be interruptible, scoped, and able to resume work without assuming that
- * the previous owner completed every in-flight action exactly once.
+ * `Singleton.make` wraps `Sharding.registerSingleton` in a `Layer`. When the
+ * local runner owns the shard for the singleton's name and shard group,
+ * sharding starts the effect; when ownership moves or the layer scope closes,
+ * the running fiber is interrupted and the registration is removed.
+ *
+ * **Mental model**
+ *
+ * A singleton is still placed on a shard. Its name and optional shard group
+ * determine the shard id, and the runner that acquires that shard lock is the
+ * only runner allowed to execute it. Failover is handled by shard ownership, so
+ * another runner can resume the singleton after the previous owner leaves.
+ *
+ * **Common tasks**
+ *
+ * - Start one scheduler, consumer, polling loop, or maintenance process for a
+ *   whole cluster
+ * - Register that process as part of application wiring with `Layer`
+ * - Choose a `shardGroup` when singleton ownership should be coordinated with a
+ *   specific group of clustered work
+ *
+ * **Gotchas**
+ *
+ * - Design the effect to be interruptible and idempotent; ownership can move
+ *   while work is in flight.
+ * - Duplicate singleton names in the same shard group fail during registration.
+ * - Handle expected failures inside the effect when it should keep running,
+ *   because unhandled failures are surfaced as defects by sharding.
  *
  * @since 4.0.0
  */
@@ -20,6 +39,29 @@ import { Sharding } from "./Sharding.ts";
  * Creates a layer that registers a singleton effect with `Sharding` under the
  * specified name and optional shard group.
  *
+ * **When to use**
+ *
+ * Use to register a cluster-wide background effect as a `Layer`, so the effect
+ * is started only by the runner that currently owns the singleton's shard.
+ *
+ * **Details**
+ *
+ * The returned layer requires `Sharding` and the services needed by `run`,
+ * except for `Scope`. The registration is scoped to the layer; closing the
+ * layer removes the singleton registration and stops the singleton fiber if it
+ * is running.
+ *
+ * **Gotchas**
+ *
+ * - Registering the same singleton name in the same shard group more than once
+ *   dies during registration.
+ * - A `run` effect that completes normally is kept alive until the registration
+ *   scope closes or shard ownership moves.
+ * - Failures from `run` are converted to defects, so handle expected failures
+ *   inside `run` when the singleton should keep running.
+ *
+ * @see {@link Sharding} for the lower-level service that registers singletons and manages shard ownership
+ *
  * @category constructors
  * @since 4.0.0
  */

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

@@ -1 +1 @@
-{"version":3,"file":"Singleton.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/Singleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EACvB,MAAM,MAAM,EACZ,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,UAAU;IACR,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACzC,KACA,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAIpD,CAAA"}
+{"version":3,"file":"Singleton.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/Singleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EACvB,MAAM,MAAM,EACZ,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,UAAU;IACR,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACzC,KACA,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAIpD,CAAA"}

package/dist/unstable/cluster/Singleton.js

@@ -1,14 +1,33 @@
 /**
- * The `Singleton` module provides a small helper for registering effects that
- * should run once across an Effect cluster. A singleton is coordinated through
- * `Sharding`, which assigns ownership to one node at a time and can move that
- * ownership when nodes leave or fail.
+ * Register effects that should have one active owner in an Effect cluster.
  *
- * Use singletons for cluster-wide background work such as schedulers, polling
- * loops, maintenance jobs, or consumers that must not have one instance per
- * process. Because ownership can change during failover, the registered effect
- * should be interruptible, scoped, and able to resume work without assuming that
- * the previous owner completed every in-flight action exactly once.
+ * `Singleton.make` wraps `Sharding.registerSingleton` in a `Layer`. When the
+ * local runner owns the shard for the singleton's name and shard group,
+ * sharding starts the effect; when ownership moves or the layer scope closes,
+ * the running fiber is interrupted and the registration is removed.
+ *
+ * **Mental model**
+ *
+ * A singleton is still placed on a shard. Its name and optional shard group
+ * determine the shard id, and the runner that acquires that shard lock is the
+ * only runner allowed to execute it. Failover is handled by shard ownership, so
+ * another runner can resume the singleton after the previous owner leaves.
+ *
+ * **Common tasks**
+ *
+ * - Start one scheduler, consumer, polling loop, or maintenance process for a
+ *   whole cluster
+ * - Register that process as part of application wiring with `Layer`
+ * - Choose a `shardGroup` when singleton ownership should be coordinated with a
+ *   specific group of clustered work
+ *
+ * **Gotchas**
+ *
+ * - Design the effect to be interruptible and idempotent; ownership can move
+ *   while work is in flight.
+ * - Duplicate singleton names in the same shard group fail during registration.
+ * - Handle expected failures inside the effect when it should keep running,
+ *   because unhandled failures are surfaced as defects by sharding.
  *
  * @since 4.0.0
  */
@@ -19,6 +38,29 @@ import { Sharding } from "./Sharding.js";
  * Creates a layer that registers a singleton effect with `Sharding` under the
  * specified name and optional shard group.
  *
+ * **When to use**
+ *
+ * Use to register a cluster-wide background effect as a `Layer`, so the effect
+ * is started only by the runner that currently owns the singleton's shard.
+ *
+ * **Details**
+ *
+ * The returned layer requires `Sharding` and the services needed by `run`,
+ * except for `Scope`. The registration is scoped to the layer; closing the
+ * layer removes the singleton registration and stops the singleton fiber if it
+ * is running.
+ *
+ * **Gotchas**
+ *
+ * - Registering the same singleton name in the same shard group more than once
+ *   dies during registration.
+ * - A `run` effect that completes normally is kept alive until the registration
+ *   scope closes or shard ownership moves.
+ * - Failures from `run` are converted to defects, so handle expected failures
+ *   inside `run` when the singleton should keep running.
+ *
+ * @see {@link Sharding} for the lower-level service that registers singletons and manages shard ownership
+ *
  * @category constructors
  * @since 4.0.0
  */

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

@@ -1 +1 @@
-{"version":3,"file":"Singleton.js","names":["Effect","Layer","Sharding","make","name","run","options","effectDiscard","gen","sharding","registerSingleton"],"sources":["../../../src/unstable/cluster/Singleton.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;AAcA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AAEvC,SAASC,QAAQ,QAAQ,eAAe;AAExC;;;;;;;AAOA,OAAO,MAAMC,IAAI,GAAGA,CAClBC,IAAY,EACZC,GAA8B,EAC9BC,OAEC,KAEDL,KAAK,CAACM,aAAa,CAACP,MAAM,CAACQ,GAAG,CAAC,aAAS;EACtC,MAAMC,QAAQ,GAAG,OAAOP,QAAQ;EAChC,OAAOO,QAAQ,CAACC,iBAAiB,CAACN,IAAI,EAAEC,GAAG,EAAEC,OAAO,CAAC;AACvD,CAAC,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"Singleton.js","names":["Effect","Layer","Sharding","make","name","run","options","effectDiscard","gen","sharding","registerSingleton"],"sources":["../../../src/unstable/cluster/Singleton.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AAEvC,SAASC,QAAQ,QAAQ,eAAe;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAO,MAAMC,IAAI,GAAGA,CAClBC,IAAY,EACZC,GAA8B,EAC9BC,OAEC,KAEDL,KAAK,CAACM,aAAa,CAACP,MAAM,CAACQ,GAAG,CAAC,aAAS;EACtC,MAAMC,QAAQ,GAAG,OAAOP,QAAQ;EAChC,OAAOO,QAAQ,CAACC,iBAAiB,CAACN,IAAI,EAAEC,GAAG,EAAEC,OAAO,CAAC;AACvD,CAAC,CAAC,CAAC","ignoreList":[]}

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

@@ -1,17 +1,31 @@
 /**
- * The `SingletonAddress` module defines the address used by cluster sharding to
- * identify a registered singleton. A singleton address combines the singleton
- * name with the `ShardId` that owns it, giving the runtime a stable key for
- * registration events, equality checks, hashing, and runner-local fiber
- * tracking.
- *
- * Use this module when observing singleton registrations or working with
- * sharding internals that need to tell which shard currently owns a singleton.
- * The shard id is derived from the singleton name and shard group at
- * registration time, so changing either value changes ownership and routing.
- * Ownership can also move as shard locks are acquired or released, so an address
- * identifies the target shard rather than guaranteeing that a particular runner
- * is currently executing the singleton.
+ * The `SingletonAddress` module models the runtime address assigned to a cluster
+ * singleton registration. The address pairs the singleton `name` with the
+ * `ShardId` selected from that name and its shard group, giving sharding one
+ * stable value for registration events, equality, hashing, and local singleton
+ * fiber tracking.
+ *
+ * **Mental model**
+ *
+ * A singleton does not have an entity id supplied by the caller. During
+ * registration, `Sharding` hashes the singleton name within a shard group and
+ * records the resulting shard id next to the name. When the local runner
+ * acquires that shard, the singleton can run; when ownership moves away, the
+ * address stays the same and the local singleton fiber is stopped.
+ *
+ * **Common tasks**
+ *
+ * - Read the address carried by singleton registration events
+ * - Compare singleton registrations by both name and shard id
+ * - Include the name and shard id in logs or diagnostics about singleton
+ *   ownership changes
+ *
+ * **Gotchas**
+ *
+ * - The same singleton name in different shard groups produces different
+ *   addresses
+ * - An address identifies the shard responsible for a singleton, not the runner
+ *   currently executing it
  *
  * @since 4.0.0
  */

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

@@ -1 +1 @@
-{"version":3,"file":"SingletonAddress.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/SingletonAddress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,eAAe,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,QAAA,MAAM,MAAM,qCAAqC,CAAA;;;;;AAEjD;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,qBAGpC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,sCAAU;IAC3B;;;;OAIG;IACH,CAAC,IAAI,CAAC,MAAM,CAAC;IAGb;;;;OAIG;IACH,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO;CAGhD"}
+{"version":3,"file":"SingletonAddress.d.ts","sourceRoot":"","sources":["../../../src/unstable/cluster/SingletonAddress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,eAAe,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,QAAA,MAAM,MAAM,qCAAqC,CAAA;;;;;AAEjD;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,qBAGpC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,sCAAU;IAC3B;;;;OAIG;IACH,CAAC,IAAI,CAAC,MAAM,CAAC;IAGb;;;;OAIG;IACH,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO;CAGhD"}

package/dist/unstable/cluster/SingletonAddress.js

@@ -1,17 +1,31 @@
 /**
- * The `SingletonAddress` module defines the address used by cluster sharding to
- * identify a registered singleton. A singleton address combines the singleton
- * name with the `ShardId` that owns it, giving the runtime a stable key for
- * registration events, equality checks, hashing, and runner-local fiber
- * tracking.
- *
- * Use this module when observing singleton registrations or working with
- * sharding internals that need to tell which shard currently owns a singleton.
- * The shard id is derived from the singleton name and shard group at
- * registration time, so changing either value changes ownership and routing.
- * Ownership can also move as shard locks are acquired or released, so an address
- * identifies the target shard rather than guaranteeing that a particular runner
- * is currently executing the singleton.
+ * The `SingletonAddress` module models the runtime address assigned to a cluster
+ * singleton registration. The address pairs the singleton `name` with the
+ * `ShardId` selected from that name and its shard group, giving sharding one
+ * stable value for registration events, equality, hashing, and local singleton
+ * fiber tracking.
+ *
+ * **Mental model**
+ *
+ * A singleton does not have an entity id supplied by the caller. During
+ * registration, `Sharding` hashes the singleton name within a shard group and
+ * records the resulting shard id next to the name. When the local runner
+ * acquires that shard, the singleton can run; when ownership moves away, the
+ * address stays the same and the local singleton fiber is stopped.
+ *
+ * **Common tasks**
+ *
+ * - Read the address carried by singleton registration events
+ * - Compare singleton registrations by both name and shard id
+ * - Include the name and shard id in logs or diagnostics about singleton
+ *   ownership changes
+ *
+ * **Gotchas**
+ *
+ * - The same singleton name in different shard groups produces different
+ *   addresses
+ * - An address identifies the shard responsible for a singleton, not the runner
+ *   currently executing it
  *
  * @since 4.0.0
  */