@einaraglen/quorum 1.0.2 → 1.0.3

package/README.md

@@ -18,13 +18,13 @@ When a pod starts up it runs an election: it contacts every peer with a higher n
 
 All coordination travels over a single internal HTTP port (default `4001`). Each pod runs a small Express server on that port with five endpoints:
 
-| Route | Purpose |
-|---|---|
-| `GET /health` | Heartbeat probe |
-| `POST /bully/election` | Incoming election challenge from a lower peer |
-| `POST /bully/coordinator` | Incoming leader announcement |
-| `POST /bully/message` | Incoming application-level event |
-| `GET /channel/stream/:event` | SSE stream for live subscriptions |
+| Route                        | Purpose                                       |
+| ---------------------------- | --------------------------------------------- |
+| `GET /health`                | Heartbeat probe                               |
+| `POST /bully/election`       | Incoming election challenge from a lower peer |
+| `POST /bully/coordinator`    | Incoming leader announcement                  |
+| `POST /bully/message`        | Incoming application-level event              |
+| `GET /channel/stream/:event` | SSE stream for live subscriptions             |
 
 The Transport class owns both sides of this: the server that listens on those routes, and the HTTP client (`postToPeer`, `pingPeer`) that sends to them.
 
@@ -32,12 +32,12 @@ The Transport class owns both sides of this: the server that listens on those ro
 
 Four messaging patterns are available, each with a different routing model:
 
-| Method | Who can call | Who receives |
-|---|---|---|
-| `broadcast(event, payload)` | Leader only | All followers + self |
-| `send(event, payload)` | Any follower | Current leader |
-| `tell(peer, event, payload)` | Leader only | One specific named peer |
-| `messagePeer(peer, event, payload)` | Anyone | One specific named peer |
+| Method                              | Who can call | Who receives            |
+| ----------------------------------- | ------------ | ----------------------- |
+| `broadcast(event, payload)`         | Leader only  | All followers + self    |
+| `send(event, payload)`              | Any follower | Current leader          |
+| `tell(peer, event, payload)`        | Leader only  | One specific named peer |
+| `messagePeer(peer, event, payload)` | Anyone       | One specific named peer |
 
 All four deliver to the pod's local `channel` EventEmitter when the target happens to be self, with no network round-trip.
 
@@ -45,7 +45,7 @@ All four deliver to the pod's local `channel` EventEmitter when the target happe
 
 `subscribeToPeer(peer, event, onData)` opens a live SSE connection to a named peer and delivers every event it emits under that name. Returns an unsubscribe function. Targets itself locally — no loopback HTTP connection.
 
-### ShardManager — work distribution
+### Sharding — work distribution
 
 The leader periodically reconciles who owns what. Reconciliation works in four steps:
 
@@ -60,20 +60,20 @@ Ownership changes drive subscriptions: `subscribe(id, onEvent)` listens to the c
 
 ### Quorum — the wrapper
 
-`Quorum` creates and wires all three layers (Transport, Bully, Forum, ShardManager) from a single options object. It is the primary entry point for production use. The individual classes are exported for testing and advanced composition.
+`Quorum` creates and wires all four layers (Transport, Bully, Forum, Sharding) from a single options object. It is the primary entry point for production use. The individual classes are exported for testing and advanced composition.
 
 ---
 
 ## Quick start
 
 ```typescript
-import { Quorum } from "quorum";
-import { getCluster } from "./my-discovery.js"; // returns { self, cluster }
+import { Quorum } from "@einaraglen/quorum";
+import { discovery } from "./my-discovery.js"; // returns { self, cluster }
 
 const q = new Quorum({
-  getCluster,
+  discovery,
   ids: ["uuid-1", "uuid-2", "uuid-3"], // the full set of work items to distribute
-  expectedClusterSize: 4,              // enables quorum protection
+  expectedClusterSize: 4, // enables quorum protection
 });
 
 q.start(); // starts the HTTP server, runs the first election, begins reconciling
@@ -89,6 +89,10 @@ q.publish("uuid-1", { reading: 42 });
 // Look up who owns an id without a network call:
 console.log(q.getOwner("uuid-1")); // "pod-name-c"
 
+// React the instant this pod gains or loses ids — no polling getHeldIds():
+q.onAssigned((ids) => console.log("now holding:", ids));
+q.onReleased((ids) => console.log("no longer holding:", ids));
+
 // Clean shutdown (or use `using q = new Quorum(...)` for automatic teardown):
 q.stop();
 ```
@@ -97,7 +101,7 @@ q.stop();
 
 ```typescript
 async function main() {
-  using q = new Quorum({ getCluster, ids });
+  using q = new Quorum({ discovery, ids });
   q.start();
 
   await new Promise<void>((resolve) => {
@@ -114,22 +118,22 @@ async function main() {
 
 ### `new Quorum(opts)`
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `getCluster` | `() => Promise<{ self, cluster }>` | required | Peer discovery. Return this pod as `self` and the full peer list (including self) as `cluster`. |
-| `ids` | `TId[]` | required | The complete set of work IDs to distribute. |
-| `fetchFn` | `typeof fetch` | `globalThis.fetch` | Swap in a custom fetch for testing. |
-| `internalPort` | `number` | `4001` or `$INTERNAL_PORT` | Port for the internal coordination server. |
-| `internalHost` | `string` | all interfaces | Bind address for the internal server. Useful in tests running multiple real instances on one machine. |
-| `requestTimeoutMs` | `number` | `2000` | Timeout for outgoing HTTP requests to peers. |
-| `coordinatorWaitMs` | `number` | `4000` | How long a pod waits for a coordinator announcement before restarting the election. |
-| `heartbeatIntervalMs` | `number` | `5000` | How often followers ping the leader to check it is still alive. |
-| `reportTimeoutMs` | `number` | `2000` | How long the leader waits for holdings reports before reconciling with whoever responded. |
-| `rebalanceIntervalMs` | `number` | `10000` | How often the leader runs a full reconcile. |
-| `expectedClusterSize` | `number` | none | Target pod count for quorum checks. |
-| `quorumFailureThreshold` | `number` | `3` | Consecutive quorum failures before `onSustainedQuorumLoss` fires. |
-| `onSustainedQuorumLoss` | `() => void` | `process.exit(1)` | Called once when the failure threshold is reached. |
-| `logger` | `Logger` | `console` | Log sink, must implement `info`/`warn`/`error`/`debug`. `console` satisfies this as-is. |
+| Option                   | Type                               | Default                    | Description                                                                                           |
+| ------------------------ | ---------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `discovery`              | `() => Promise<{ self, cluster }>` | required                   | Peer discovery. Return this pod as `self` and the full peer list (including self) as `cluster`.       |
+| `ids`                    | `TId[]`                            | required                   | The complete set of work IDs to distribute.                                                           |
+| `fetchFn`                | `typeof fetch`                     | `globalThis.fetch`         | Swap in a custom fetch for testing.                                                                   |
+| `internalPort`           | `number`                           | `4001` or `$INTERNAL_PORT` | Port for the internal coordination server.                                                            |
+| `internalHost`           | `string`                           | all interfaces             | Bind address for the internal server. Useful in tests running multiple real instances on one machine. |
+| `requestTimeoutMs`       | `number`                           | `2000`                     | Timeout for outgoing HTTP requests to peers.                                                          |
+| `coordinatorWaitMs`      | `number`                           | `4000`                     | How long a pod waits for a coordinator announcement before restarting the election.                   |
+| `heartbeatIntervalMs`    | `number`                           | `5000`                     | How often followers ping the leader to check it is still alive.                                       |
+| `reportTimeoutMs`        | `number`                           | `2000`                     | How long the leader waits for holdings reports before reconciling with whoever responded.             |
+| `rebalanceIntervalMs`    | `number`                           | `10000`                    | How often the leader runs a full reconcile.                                                           |
+| `expectedClusterSize`    | `number`                           | none                       | Target pod count for quorum checks.                                                                   |
+| `quorumFailureThreshold` | `number`                           | `3`                        | Consecutive quorum failures before `onSustainedQuorumLoss` fires.                                     |
+| `onSustainedQuorumLoss`  | `() => void`                       | `process.exit(1)`          | Called once when the failure threshold is reached.                                                    |
+| `logger`                 | `Logger`                           | `console`                  | Log sink, must implement `info`/`warn`/`error`/`debug`. `console` satisfies this as-is.               |
 
 **Methods:**
 
@@ -146,6 +150,9 @@ q.getOwner(id): string | undefined     // local lookup — no network call
 q.getOwnership(): Map<TId, string>     // full id→peer map as of last reconcile
 q.getHeldIds(): TId[]                  // ids currently assigned to this pod
 q.updateIds(ids): Promise<void>        // leader-only: replace the full id set and reconcile
+
+q.onAssigned(onEvent): () => void      // fires with the ids just gained when held ids grow
+q.onReleased(onEvent): () => void      // fires with the ids just lost when held ids shrink
 ```
 
 ---
@@ -155,12 +162,12 @@ q.updateIds(ids): Promise<void>        // leader-only: replace the full id set a
 For testing or custom wiring you can create the layers individually:
 
 ```typescript
-import { Transport, Bully, Forum, ShardManager } from "quorum";
+import { Transport, Bully, Forum, Sharding } from "@einaraglen/quorum";
 
 const transport = new Transport({ fetchFn: mockFetch, internalPort: 9000 });
-const bully = new Bully({ getCluster, transport });
-const forum = new Forum({ bully, transport, getCluster });
-const shard = new ShardManager({ bully, forum, ids: [] });
+const bully = new Bully({ discovery, transport });
+const forum = new Forum({ bully, transport, discovery });
+const shard = new Sharding({ bully, forum, ids: [] });
 
 // Wire the transport callbacks manually:
 transport.start({
@@ -183,12 +190,15 @@ await bully.startElection();
 bully.channel.emit("assign-connections", [7, 12, 44]);
 
 // Simulate the leader publishing an updated ownership map:
-bully.channel.emit("ownership-map", [[7, "pod-c"], [12, "pod-a"]]);
+bully.channel.emit("ownership-map", [
+  [7, "pod-c"],
+  [12, "pod-a"],
+]);
 ```
 
 ### Lifecycle events
 
-`bully.lifecycle` emits `"elected"` when this pod becomes leader (after peers have been notified), and `"demoted"` when it steps down. ShardManager uses these internally; you can also listen directly:
+`bully.lifecycle` emits `"elected"` when this pod becomes leader (after peers have been notified), and `"demoted"` when it steps down. Sharding uses these internally; you can also listen directly:
 
 ```typescript
 bully.lifecycle.on("elected", () => {
@@ -199,11 +209,22 @@ bully.lifecycle.on("demoted", () => {
 });
 ```
 
+`shard.lifecycle` similarly emits `"assigned"` and `"released"`, each with the delta of ids that just changed (not the full held set) — this is what `Quorum.onAssigned`/`onReleased` wrap:
+
+```typescript
+shard.lifecycle.on("assigned", (ids) => {
+  console.log("now holding:", ids);
+});
+shard.lifecycle.on("released", (ids) => {
+  console.log("no longer holding:", ids);
+});
+```
+
 ---
 
 ## Peer discovery
 
-`getCluster` is the only application-specific piece. It must return:
+`discovery` is the only application-specific piece. It must return:
 
 ```typescript
 {
@@ -216,7 +237,7 @@ bully.lifecycle.on("demoted", () => {
 
 ```typescript
 // In your application layer (not in quorum itself):
-const getCluster = async () => {
+const discovery = async () => {
   const pods = await k8s.listNamespacedPod({
     namespace: "default",
     labelSelector: "app=my-service",
@@ -255,5 +276,5 @@ src/
 Every class (and `Quorum` itself) accepts an optional `logger` implementing `info`/`warn`/`error`/`debug` — `console` satisfies this shape as-is and is the default. Pass your own (winston, pino, a wrapper around your APM, etc.) to route quorum's election/reconcile/messaging logs wherever the rest of your app's logs go:
 
 ```typescript
-const q = new Quorum({ getCluster, ids, logger: myWinstonLogger });
+const q = new Quorum({ discovery, ids, logger: myWinstonLogger });
 ```

package/dist/core/bully.d.ts

@@ -9,9 +9,9 @@ export type BullyCluster = {
     self: BullyPeer;
     cluster: BullyPeer[];
 };
-export type GetCluster = () => Promise<BullyCluster>;
+export type Discovery = () => Promise<BullyCluster>;
 export type BullyOptions = {
-    getCluster: GetCluster;
+    discovery: Discovery;
     transport: Transport;
     coordinatorWaitMs?: number;
     heartbeatIntervalMs?: number;
@@ -20,7 +20,7 @@ export type BullyOptions = {
 export declare class Bully implements Disposable {
     readonly lifecycle: EventEmitter<[never]>;
     readonly channel: EventEmitter<[never]>;
-    private readonly getClusterFn;
+    private readonly discovery;
     private readonly transport;
     private readonly coordinatorWaitMs;
     private readonly heartbeatIntervalMs;

package/dist/core/bully.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bully.d.ts","sourceRoot":"","sources":["../../src/core/bully.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AACrE,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,KAAM,YAAW,UAAU;IACtC,SAAgB,SAAS,wBAAsB;IAC/C,SAAgB,OAAO,wBAAsB;IAE7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,sBAAsB,CAAC,CAAiB;IAChD,OAAO,CAAC,iBAAiB,CAAC,CAAiB;IAE3C,YAAY,IAAI,EAAE,YAAY,EAM7B;IAEM,QAAQ,IAAI,OAAO,CAEzB;IAEM,SAAS;QACL,IAAI;QAAe,MAAM;QAAiB,QAAQ;MAC5D;IAEY,WAAW;;;;SAOvB;IAED,4EAA4E;IAC/D,QAAQ,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAI5C;YAEa,YAAY;IAeb,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAkC1C;IAEM,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG7C;IAEM,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAa5C;IAEM,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAEtD;IAEM,KAAK,IAAI,IAAI,CAuBnB;IAEM,IAAI,IAAI,IAAI,CAIlB;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAE9B;CACF"}
+{"version":3,"file":"bully.d.ts","sourceRoot":"","sources":["../../src/core/bully.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AACrE,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;AAEpD,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,KAAM,YAAW,UAAU;IACtC,SAAgB,SAAS,wBAAsB;IAC/C,SAAgB,OAAO,wBAAsB;IAE7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,sBAAsB,CAAC,CAAiB;IAChD,OAAO,CAAC,iBAAiB,CAAC,CAAiB;IAE3C,YAAY,IAAI,EAAE,YAAY,EAM7B;IAEM,QAAQ,IAAI,OAAO,CAEzB;IAEM,SAAS;QACL,IAAI;QAAe,MAAM;QAAiB,QAAQ;MAC5D;IAEY,WAAW;;;;SAOvB;IAED,4EAA4E;IAC/D,QAAQ,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAI5C;YAEa,YAAY;IAeb,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAkC1C;IAEM,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG7C;IAEM,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAa5C;IAEM,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAEtD;IAEM,KAAK,IAAI,IAAI,CAuBnB;IAEM,IAAI,IAAI,IAAI,CAIlB;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAE9B;CACF"}

package/dist/core/bully.js

@@ -2,7 +2,7 @@ import { EventEmitter } from "events";
 export class Bully {
     lifecycle = new EventEmitter();
     channel = new EventEmitter();
-    getClusterFn;
+    discovery;
     transport;
     coordinatorWaitMs;
     heartbeatIntervalMs;
@@ -13,7 +13,7 @@ export class Bully {
     coordinatorWaitTimeout;
     heartbeatInterval;
     constructor(opts) {
-        this.getClusterFn = opts.getCluster;
+        this.discovery = opts.discovery;
         this.transport = opts.transport;
         this.coordinatorWaitMs = opts.coordinatorWaitMs ?? 4000;
         this.heartbeatIntervalMs = opts.heartbeatIntervalMs ?? 5000;
@@ -26,7 +26,7 @@ export class Bully {
         return { self: this.selfId, leader: this.leaderId, isLeader: this.isLeader() };
     }
     async getPodRoles() {
-        const { cluster } = await this.getClusterFn();
+        const { cluster } = await this.discovery();
         return cluster.map((pod) => ({
             name: pod.name,
             host: pod.host,
@@ -35,7 +35,7 @@ export class Bully {
     }
     /** Returns all cluster peers except self. Side-effect: populates selfId. */
     async getPeers() {
-        const { self, cluster } = await this.getClusterFn();
+        const { self, cluster } = await this.discovery();
         this.selfId = self.name;
         return cluster.filter((pod) => pod.name !== self.name && pod.host);
     }
@@ -46,7 +46,7 @@ export class Bully {
             this.logger.info(`Became leader (id=${this.selfId})`);
         await Promise.all(peers.map((peer) => this.transport.postToPeer(peer.host, "/bully/coordinator", { id: this.selfId })));
         // Emitted only after peers have been told, so an "elected" listener that immediately talks
-        // to peers (e.g. ShardManager.reconcile()) doesn't race ahead of them learning who's leader.
+        // to peers (e.g. Sharding.reconcile()) doesn't race ahead of them learning who's leader.
         if (!wasLeader)
             this.lifecycle.emit("elected");
     }

package/dist/core/forum.d.ts

@@ -1,17 +1,17 @@
 import type { Logger } from "./logger";
-import type { Bully, BullyPeer, GetCluster } from "./bully";
+import type { Bully, BullyPeer, Discovery } from "./bully";
 import type { Transport } from "./transport";
 export type ForumOptions = {
     bully: Bully;
     transport: Transport;
-    getCluster: GetCluster;
+    discovery: Discovery;
     fetchFn?: typeof fetch;
     logger?: Logger;
 };
 export declare class Forum {
     private readonly bully;
     private readonly transport;
-    private readonly getClusterFn;
+    private readonly discovery;
     private readonly fetchFn;
     private readonly logger;
     constructor(opts: ForumOptions);

package/dist/core/forum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forum.d.ts","sourceRoot":"","sources":["../../src/core/forum.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YAAY,IAAI,EAAE,YAAY,EAM7B;IAED,sFAAsF;IACzE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAUtE;IAED,+EAA+E;IAClE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBjE;IAED,kFAAkF;IACrE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnF;IAED;;;OAGG;IACU,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1F;IAED;;;OAGG;IACU,UAAU,CAAC,CAAC,EACvB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,GAC3E,OAAO,CAAC,IAAI,CAAC,CAqBf;IAED;;;;OAIG;IACI,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAgEtG;CACF"}
+{"version":3,"file":"forum.d.ts","sourceRoot":"","sources":["../../src/core/forum.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YAAY,IAAI,EAAE,YAAY,EAM7B;IAED,sFAAsF;IACzE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQtE;IAED,+EAA+E;IAClE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBjE;IAED,kFAAkF;IACrE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnF;IAED;;;OAGG;IACU,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1F;IAED;;;OAGG;IACU,UAAU,CAAC,CAAC,EACvB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,GAC3E,OAAO,CAAC,IAAI,CAAC,CAoBf;IAED;;;;OAIG;IACI,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CA+DtG;CACF"}

package/dist/core/forum.js

@@ -1,13 +1,13 @@
 export class Forum {
     bully;
     transport;
-    getClusterFn;
+    discovery;
     fetchFn;
     logger;
     constructor(opts) {
         this.bully = opts.bully;
         this.transport = opts.transport;
-        this.getClusterFn = opts.getCluster;
+        this.discovery = opts.discovery;
         this.fetchFn = opts.fetchFn ?? this.transport.fetchFn;
         this.logger = opts.logger ?? console;
     }
@@ -75,11 +75,8 @@ export class Forum {
             this.logger.warn(`distribute('${event}') called while not leader, ignoring`);
             return;
         }
-        const { self, cluster } = await this.getClusterFn();
-        const allPeers = [
-            self,
-            ...cluster.filter((pod) => pod.name !== self.name && pod.host),
-        ].sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+        const { self, cluster } = await this.discovery();
+        const allPeers = [self, ...cluster.filter((pod) => pod.name !== self.name && pod.host)].sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
         await Promise.all(allPeers.map((peer, index) => {
             const payload = resolvePayload(peer, index, allPeers);
             if (peer.name === self.name) {
@@ -110,7 +107,9 @@ export class Forum {
                 return;
             }
             try {
-                const res = await this.fetchFn(`http://${target.host}:${this.transport.port}/channel/stream/${event}`, { signal: controller.signal });
+                const res = await this.fetchFn(`http://${target.host}:${this.transport.port}/channel/stream/${event}`, {
+                    signal: controller.signal,
+                });
                 if (!res.ok || !res.body) {
                     this.logger.warn(`subscribeToPeer('${event}') to '${peerName}' failed to connect`);
                     return;

package/dist/core/quorum.d.ts

@@ -1,7 +1,7 @@
-import { type GetCluster } from "./bully";
+import { type Discovery } from "./bully";
 import type { Logger } from "./logger";
 export type QuorumOptions<TId = string> = {
-    getCluster: GetCluster;
+    discovery: Discovery;
     ids: TId[];
     fetchFn?: typeof fetch;
     internalPort?: number;
@@ -40,6 +40,10 @@ export declare class Quorum<TId = string> implements Disposable {
     getOwnership(): Map<TId, string>;
     getHeldIds(): TId[];
     updateIds(ids: TId[]): Promise<void>;
+    /** Fires with the ids just gained whenever this pod's held ids grow. Returns an unsubscribe function. */
+    onAssigned(onEvent: (ids: TId[]) => void): () => void;
+    /** Fires with the ids just lost whenever this pod's held ids shrink. Returns an unsubscribe function. */
+    onReleased(onEvent: (ids: TId[]) => void): () => void;
     start(): void;
     stop(): void;
     [Symbol.dispose](): void;

package/dist/core/quorum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quorum.d.ts","sourceRoot":"","sources":["../../src/core/quorum.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,aAAa,CAAC,GAAG,GAAG,MAAM,IAAI;IACxC,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,EAAE,GAAG,EAAE,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,MAAM,CAAC,GAAG,GAAG,MAAM,CAAE,YAAW,UAAU;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAE1C,YAAY,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,EAiCnC;IAEM,QAAQ,IAAI,OAAO,CAAkC;IACrD,SAAS;;;;MAAqC;IACxC,WAAW;;;;SAAuC;IAExD,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAEzE;IACM,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAqC;IAC7E,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAAoC;IACzE,YAAY,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAsC;IACtE,UAAU,IAAI,GAAG,EAAE,CAAoC;IACjD,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAsC;IAEhF,KAAK,IAAI,IAAI,CAUnB;IAEM,IAAI,IAAI,IAAI,CAIlB;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAE9B;CACF"}
+{"version":3,"file":"quorum.d.ts","sourceRoot":"","sources":["../../src/core/quorum.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAGhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,aAAa,CAAC,GAAG,GAAG,MAAM,IAAI;IACxC,SAAS,EAAE,SAAS,CAAC;IACrB,GAAG,EAAE,GAAG,EAAE,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,MAAM,CAAC,GAAG,GAAG,MAAM,CAAE,YAAW,UAAU;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IAEtC,YAAY,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,EAiCnC;IAEM,QAAQ,IAAI,OAAO,CAEzB;IACM,SAAS;;;;MAEf;IACY,WAAW;;;;SAEvB;IAEM,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAEzE;IACM,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAE9C;IACM,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAE3C;IACM,YAAY,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAEtC;IACM,UAAU,IAAI,GAAG,EAAE,CAEzB;IACY,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhD;IAED,yGAAyG;IAClG,UAAU,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAG3D;IACD,yGAAyG;IAClG,UAAU,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAG3D;IAEM,KAAK,IAAI,IAAI,CAUnB;IAEM,IAAI,IAAI,IAAI,CAIlB;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAE9B;CACF"}

package/dist/core/quorum.js

@@ -1,7 +1,7 @@
 import { Transport } from "./transport";
 import { Bully } from "./bully";
 import { Forum } from "./forum";
-import { ShardManager } from "./sharding";
+import { Sharding } from "./sharding";
 export class Quorum {
     transport;
     bully;
@@ -16,7 +16,7 @@ export class Quorum {
             logger: opts.logger,
         });
         this.bully = new Bully({
-            getCluster: opts.getCluster,
+            discovery: opts.discovery,
             transport: this.transport,
             coordinatorWaitMs: opts.coordinatorWaitMs,
             heartbeatIntervalMs: opts.heartbeatIntervalMs,
@@ -25,11 +25,11 @@ export class Quorum {
         this.forum = new Forum({
             bully: this.bully,
             transport: this.transport,
-            getCluster: opts.getCluster,
+            discovery: opts.discovery,
             fetchFn: opts.fetchFn,
             logger: opts.logger,
         });
-        this.shard = new ShardManager({
+        this.shard = new Sharding({
             bully: this.bully,
             forum: this.forum,
             ids: opts.ids,
@@ -41,17 +41,43 @@ export class Quorum {
             logger: opts.logger,
         });
     }
-    isLeader() { return this.bully.isLeader(); }
-    getStatus() { return this.bully.getStatus(); }
-    async getPodRoles() { return this.bully.getPodRoles(); }
+    isLeader() {
+        return this.bully.isLeader();
+    }
+    getStatus() {
+        return this.bully.getStatus();
+    }
+    async getPodRoles() {
+        return this.bully.getPodRoles();
+    }
     subscribe(id, onEvent) {
         return this.shard.subscribe(id, onEvent);
     }
-    publish(id, payload) { this.shard.publish(id, payload); }
-    getOwner(id) { return this.shard.getOwner(id); }
-    getOwnership() { return this.shard.getOwnership(); }
-    getHeldIds() { return this.shard.getHeldIds(); }
-    async updateIds(ids) { return this.shard.updateIds(ids); }
+    publish(id, payload) {
+        this.shard.publish(id, payload);
+    }
+    getOwner(id) {
+        return this.shard.getOwner(id);
+    }
+    getOwnership() {
+        return this.shard.getOwnership();
+    }
+    getHeldIds() {
+        return this.shard.getHeldIds();
+    }
+    async updateIds(ids) {
+        return this.shard.updateIds(ids);
+    }
+    /** Fires with the ids just gained whenever this pod's held ids grow. Returns an unsubscribe function. */
+    onAssigned(onEvent) {
+        this.shard.lifecycle.on("assigned", onEvent);
+        return () => this.shard.lifecycle.off("assigned", onEvent);
+    }
+    /** Fires with the ids just lost whenever this pod's held ids shrink. Returns an unsubscribe function. */
+    onReleased(onEvent) {
+        this.shard.lifecycle.on("released", onEvent);
+        return () => this.shard.lifecycle.off("released", onEvent);
+    }
     start() {
         this.transport.start({
             onElectionMessage: (id) => this.bully.onElectionMessage(id),

package/dist/core/sharding.d.ts

@@ -1,7 +1,8 @@
+import { EventEmitter } from "events";
 import type { Bully } from "./bully";
 import type { Forum } from "./forum";
 import type { Logger } from "./logger";
-export type ShardManagerOptions<TId> = {
+export type ShardingOptions<TId> = {
     bully: Bully;
     forum: Forum;
     ids: TId[];
@@ -29,7 +30,9 @@ export type ShardManagerOptions<TId> = {
     onSustainedQuorumLoss?: () => void;
     logger?: Logger;
 };
-export declare class ShardManager<TId = string> implements Disposable {
+export declare class Sharding<TId = string> implements Disposable {
+    /** Emits `"assigned"` / `"released"` (each with the delta of ids, not the full held set) whenever this pod's held ids change. */
+    readonly lifecycle: EventEmitter<[never]>;
     private bully;
     private forum;
     private allIds;
@@ -42,6 +45,8 @@ export declare class ShardManager<TId = string> implements Disposable {
     private consecutiveQuorumFailures;
     /** Ensures sustainedQuorumLossCallback fires once per episode, not on every failure past threshold. */
     private hasTriggeredSustainedLoss;
+    /** Guards against a periodic rebalance tick overlapping an explicit reconcile() already in flight. */
+    private reconcileInFlight;
     private heldIds;
     private ownership;
     private rebalanceInterval?;
@@ -49,7 +54,7 @@ export declare class ShardManager<TId = string> implements Disposable {
     private ownershipEvents;
     /** Safety net: any subscribe() the caller never explicitly closed gets torn down in stop(). */
     private activeSubscriptions;
-    constructor(opts: ShardManagerOptions<TId>);
+    constructor(opts: ShardingOptions<TId>);
     getHeldIds(): TId[];
     /** Local, instant lookup — no network round-trip — of which peer currently owns an id. */
     getOwner(id: TId): string | undefined;
@@ -90,5 +95,6 @@ export declare class ShardManager<TId = string> implements Disposable {
      * assign/release messages needed to converge on that target.
      */
     reconcile(): Promise<void>;
+    private doReconcile;
 }
 //# sourceMappingURL=sharding.d.ts.map

package/dist/core/sharding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sharding.d.ts","sourceRoot":"","sources":["../../src/core/sharding.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,mBAAmB,CAAC,GAAG,IAAI;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,GAAG,EAAE,CAAC;IACX,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAKF,qBAAa,YAAY,CAAC,GAAG,GAAG,MAAM,CAAE,YAAW,UAAU;IAC3D,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,mBAAmB,CAAC,CAAS;IACrC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,2BAA2B,CAAa;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,yBAAyB,CAAK;IACtC,uGAAuG;IACvG,OAAO,CAAC,yBAAyB,CAAS;IAC1C,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,iBAAiB,CAAC,CAAiB;IAC3C,+FAA+F;IAC/F,OAAO,CAAC,eAAe,CAAsB;IAC7C,+FAA+F;IAC/F,OAAO,CAAC,mBAAmB,CAAyB;IAEpD,YAAY,IAAI,EAAE,mBAAmB,CAAC,GAAG,CAAC,EAUzC;IAEM,UAAU,UAEhB;IAED,0FAA0F;IACnF,QAAQ,CAAC,EAAE,EAAE,GAAG,sBAEtB;IAED,kGAAkG;IAC3F,YAAY,qBAElB;IAED;;;;;;;OAOG;IACI,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CA+BzE;IAED,sFAAsF;IAC/E,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,QAMvC;IAED,OAAO,CAAC,QAAQ,CAGd;IAEF,OAAO,CAAC,SAAS,CAGf;IAEF,OAAO,CAAC,eAAe,CAIrB;IAEF,OAAO,CAAC,WAAW,CAEjB;IAEF,OAAO,CAAC,cAAc,CAUpB;IAEF,OAAO,CAAC,SAAS,CAGf;IAEF,OAAO,CAAC,SAAS,CAKf;IAEK,KAAK,SAQX;IAEM,IAAI,SAWV;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC,SAEtB;IAED;;;;;OAKG;IACU,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,iBAQhC;IAED;;;;;OAKG;IACU,SAAS,kBA0FrB;CACF"}
+{"version":3,"file":"sharding.d.ts","sourceRoot":"","sources":["../../src/core/sharding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,eAAe,CAAC,GAAG,IAAI;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,GAAG,EAAE,CAAC;IACX,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAKF,qBAAa,QAAQ,CAAC,GAAG,GAAG,MAAM,CAAE,YAAW,UAAU;IACvD,iIAAiI;IACjI,SAAgB,SAAS,wBAAsB;IAE/C,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,mBAAmB,CAAC,CAAS;IACrC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,2BAA2B,CAAa;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,yBAAyB,CAAK;IACtC,uGAAuG;IACvG,OAAO,CAAC,yBAAyB,CAAS;IAC1C,sGAAsG;IACtG,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,iBAAiB,CAAC,CAAiB;IAC3C,+FAA+F;IAC/F,OAAO,CAAC,eAAe,CAAsB;IAC7C,+FAA+F;IAC/F,OAAO,CAAC,mBAAmB,CAAyB;IAEpD,YAAY,IAAI,EAAE,eAAe,CAAC,GAAG,CAAC,EAUrC;IAEM,UAAU,UAEhB;IAED,0FAA0F;IACnF,QAAQ,CAAC,EAAE,EAAE,GAAG,sBAEtB;IAED,kGAAkG;IAC3F,YAAY,qBAElB;IAED;;;;;;;OAOG;IACI,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CA+BzE;IAED,sFAAsF;IAC/E,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,QAMvC;IAED,OAAO,CAAC,QAAQ,CAId;IAEF,OAAO,CAAC,SAAS,CAIf;IAEF,OAAO,CAAC,eAAe,CAIrB;IAEF,OAAO,CAAC,WAAW,CAEjB;IAEF,OAAO,CAAC,cAAc,CAUpB;IAEF,OAAO,CAAC,SAAS,CAGf;IAEF,OAAO,CAAC,SAAS,CAKf;IAEK,KAAK,SAQX;IAEM,IAAI,SAWV;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC,SAEtB;IAED;;;;;OAKG;IACU,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,iBAQhC;IAED;;;;;OAKG;IACU,SAAS,kBASrB;YAEa,WAAW;CA2F1B"}

package/dist/core/sharding.js

@@ -1,5 +1,7 @@
 import { EventEmitter } from "events";
-export class ShardManager {
+export class Sharding {
+    /** Emits `"assigned"` / `"released"` (each with the delta of ids, not the full held set) whenever this pod's held ids change. */
+    lifecycle = new EventEmitter();
     bully;
     forum;
     allIds;
@@ -12,6 +14,8 @@ export class ShardManager {
     consecutiveQuorumFailures = 0;
     /** Ensures sustainedQuorumLossCallback fires once per episode, not on every failure past threshold. */
     hasTriggeredSustainedLoss = false;
+    /** Guards against a periodic rebalance tick overlapping an explicit reconcile() already in flight. */
+    reconcileInFlight = false;
     heldIds = new Set();
     ownership = new Map();
     rebalanceInterval;
@@ -89,11 +93,13 @@ export class ShardManager {
         for (const id of ids)
             this.heldIds.add(id);
         this.logger.debug(`Now holding ${this.heldIds.size} id(s)`);
+        this.lifecycle.emit("assigned", ids);
     };
     onRelease = (ids) => {
         for (const id of ids)
             this.heldIds.delete(id);
         this.logger.debug(`Released ${ids.length} id(s), now holding ${this.heldIds.size}`);
+        this.lifecycle.emit("released", ids);
     };
     onReportRequest = () => {
         const { self } = this.bully.getStatus();
@@ -144,7 +150,7 @@ export class ShardManager {
         this.bully.lifecycle.off("elected", this.onElected);
         this.bully.lifecycle.off("demoted", this.onDemoted);
         this.onDemoted();
-        for (const unsubscribe of [...this.activeSubscriptions])
+        for (const unsubscribe of this.activeSubscriptions)
             unsubscribe();
     }
     [Symbol.dispose]() {
@@ -171,6 +177,17 @@ export class ShardManager {
      * assign/release messages needed to converge on that target.
      */
     async reconcile() {
+        if (this.reconcileInFlight)
+            return;
+        this.reconcileInFlight = true;
+        try {
+            await this.doReconcile();
+        }
+        finally {
+            this.reconcileInFlight = false;
+        }
+    }
+    async doReconcile() {
         const reports = new Map();
         const { self } = this.bully.getStatus();
         if (self)

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 export { Quorum } from "./core/quorum";
 export type { QuorumOptions } from "./core/quorum";
 export { Bully } from "./core/bully";
-export type { BullyPeer, BullyCluster, GetCluster, BullyOptions } from "./core/bully";
+export type { BullyPeer, BullyCluster, Discovery, BullyOptions } from "./core/bully";
 export { Forum } from "./core/forum";
 export type { ForumOptions } from "./core/forum";
 export { Transport } from "./core/transport";
 export type { TransportOptions, TransportCallbacks } from "./core/transport";
-export { ShardManager } from "./core/sharding";
-export type { ShardManagerOptions } from "./core/sharding";
+export { Sharding } from "./core/sharding";
+export type { ShardingOptions } from "./core/sharding";
 export type { Logger } from "./core/logger";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEtF,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE7E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,YAAY,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAErF,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE7E,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,YAAY,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -2,4 +2,4 @@ export { Quorum } from "./core/quorum";
 export { Bully } from "./core/bully";
 export { Forum } from "./core/forum";
 export { Transport } from "./core/transport";
-export { ShardManager } from "./core/sharding";
+export { Sharding } from "./core/sharding";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@einaraglen/quorum",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Distributed pod coordination: Bully leader election and work sharding",
   "keywords": [
     "leader-election",
@@ -29,11 +29,17 @@
   },
   "scripts": {
     "test": "tsx --test --test-reporter=spec --test-reporter-destination=stdout src/**/*.test.ts",
-    "build": "tsc"
+    "build": "tsc",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "oxlint .",
+    "check": "npm run format:check && npm run lint"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
     "@types/node": "^24.9.2",
+    "oxlint": "^1.80.0",
+    "prettier": "^3.9.6",
     "tsx": "^4.23.12",
     "typescript": "^7.0.2"
   },