actor-ts 0.9.0

package/dist/cluster/router/ConsistentHashing.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Consistent-hashing primitive for `ClusterRouter` — pinning a key to
+ * one routee out of an N-routee set, with the property that adding or
+ * removing a routee re-routes only **1/N** of keys instead of (1 − 1/N).
+ *
+ * We use **rendezvous hashing** (a.k.a. highest-random-weight): for
+ * each candidate, hash `(key, candidateId)` together and pick the
+ * candidate with the highest hash.  The "candidateId" is whatever
+ * stable string identifies the routee — typically its node address.
+ *
+ *   pickRendezvous('order-42', addrs)   // → addrs[k]
+ *   pickRendezvous('order-42', addrs)   // → same addrs[k] — stable
+ *   pickRendezvous('order-42', addrs.slice(0, -1))
+ *     // → still addrs[k] unless k was the dropped one
+ *
+ * The hash is FNV-1a-derived (same family used by `ShardAllocator`),
+ * so behaviour is consistent across the codebase and across nodes.
+ */
+/**
+ * Pick the candidate with the highest combined-hash for `key`.
+ * `candidates` is iterated in order; ties are broken by first-occurrence
+ * to keep behaviour deterministic given identical inputs.
+ *
+ * Throws if `candidates` is empty — callers should check beforehand.
+ */
+export declare function pickRendezvous<T>(key: string, candidates: ReadonlyArray<T>, identityOf: (c: T) => string): T;
+//# sourceMappingURL=ConsistentHashing.d.ts.map

package/dist/cluster/router/ConsistentHashing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsistentHashing.d.ts","sourceRoot":"","sources":["../../../src/cluster/router/ConsistentHashing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,EAC5B,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,GAC3B,CAAC,CAWH"}

package/dist/cluster/router/ConsistentHashing.js

@@ -0,0 +1,69 @@
+/**
+ * Consistent-hashing primitive for `ClusterRouter` — pinning a key to
+ * one routee out of an N-routee set, with the property that adding or
+ * removing a routee re-routes only **1/N** of keys instead of (1 − 1/N).
+ *
+ * We use **rendezvous hashing** (a.k.a. highest-random-weight): for
+ * each candidate, hash `(key, candidateId)` together and pick the
+ * candidate with the highest hash.  The "candidateId" is whatever
+ * stable string identifies the routee — typically its node address.
+ *
+ *   pickRendezvous('order-42', addrs)   // → addrs[k]
+ *   pickRendezvous('order-42', addrs)   // → same addrs[k] — stable
+ *   pickRendezvous('order-42', addrs.slice(0, -1))
+ *     // → still addrs[k] unless k was the dropped one
+ *
+ * The hash is FNV-1a-derived (same family used by `ShardAllocator`),
+ * so behaviour is consistent across the codebase and across nodes.
+ */
+/**
+ * Pick the candidate with the highest combined-hash for `key`.
+ * `candidates` is iterated in order; ties are broken by first-occurrence
+ * to keep behaviour deterministic given identical inputs.
+ *
+ * Throws if `candidates` is empty — callers should check beforehand.
+ */
+export function pickRendezvous(key, candidates, identityOf) {
+    if (candidates.length === 0) {
+        throw new Error('pickRendezvous: candidates list is empty');
+    }
+    let bestHash = -1;
+    let best = candidates[0];
+    for (const c of candidates) {
+        const h = hashCombine(key, identityOf(c));
+        if (h > bestHash) {
+            bestHash = h;
+            best = c;
+        }
+    }
+    return best;
+}
+/* ------------------------------ helpers --------------------------------- */
+/**
+ * FNV-1a 32-bit string hash — same algorithm `ShardAllocator` uses for
+ * shard-id hashing.  Stable across runtimes; not cryptographically
+ * strong but plenty for routing.
+ */
+function fnv1a(s) {
+    let h = 2166136261; // FNV-1a 32-bit basis
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h;
+}
+/**
+ * Mix two strings into a single 32-bit unsigned integer.  Deliberately
+ * symmetric in the sense that callers can think of the inputs as a
+ * pair (key, candidateId) — but order **does** matter (the second
+ * argument is mixed into the hash of the first), which is what we
+ * want: `hashCombine('a', 'b') !== hashCombine('b', 'a')` keeps the
+ * (key, candidate) pairing meaningful.
+ */
+function hashCombine(a, b) {
+    let h = fnv1a(a) ^ Math.imul(fnv1a(b), 2654435761);
+    h ^= h >>> 13;
+    h = Math.imul(h, 1540483477);
+    return h >>> 0;
+}
+//# sourceMappingURL=ConsistentHashing.js.map

package/dist/cluster/router/ConsistentHashing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsistentHashing.js","sourceRoot":"","sources":["../../../src/cluster/router/ConsistentHashing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,UAA4B,EAC5B,UAA4B;IAE5B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC;IAClB,IAAI,IAAI,GAAM,UAAU,CAAC,CAAC,CAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;YAAC,QAAQ,GAAG,CAAC,CAAC;YAAC,IAAI,GAAG,CAAC,CAAC;QAAC,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAE9E;;;;GAIG;AACH,SAAS,KAAK,CAAC,CAAS;IACtB,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC,sBAAsB;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,CAAS,EAAE,CAAS;IACvC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IACnD,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACd,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC7B,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC"}

package/dist/cluster/router/index.d.ts

@@ -0,0 +1,4 @@
+export { ClusterRouter } from './ClusterRouter.js';
+export type { ClusterRouterOptions, ClusterRouterType, } from './ClusterRouter.js';
+export { pickRendezvous } from './ConsistentHashing.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cluster/router/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cluster/router/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/cluster/router/index.js

@@ -0,0 +1,3 @@
+export { ClusterRouter } from './ClusterRouter.js';
+export { pickRendezvous } from './ConsistentHashing.js';
+//# sourceMappingURL=index.js.map

package/dist/cluster/router/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cluster/router/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/cluster/sharding/AllocationStrategy.d.ts

@@ -0,0 +1,45 @@
+import { NodeAddress } from '../NodeAddress.js';
+/**
+ * Instructs the ShardCoordinator how to place and rebalance shards.
+ *
+ * `allocate` is called when a shard needs a new home — e.g. right after it
+ * is first requested.  `rebalance` is called periodically so strategies can
+ * move shards away from busy nodes.
+ */
+export interface AllocationStrategy {
+    /** Pick an owner for a newly-discovered shard. */
+    allocate(shardId: number, candidates: ReadonlyArray<NodeAddress>, currentShards: ReadonlyMap<string, ReadonlySet<number>>): NodeAddress;
+    /**
+     * Return a set of shard ids that should be re-homed.  The coordinator
+     * will send HandOff for each and then allocate() a new home once the
+     * handoff completes.
+     */
+    rebalance(currentShards: ReadonlyMap<string, ReadonlySet<number>>, candidates: ReadonlyArray<NodeAddress>, rebalanceInProgress: ReadonlySet<number>): Set<number>;
+}
+/**
+ * Hash-based: allocate by modulo on the sorted candidate list.  Simple,
+ * deterministic, minimal rebalance behaviour (only moves shards when the
+ * candidate set changes).
+ */
+export declare class HashAllocationStrategy implements AllocationStrategy {
+    allocate(shardId: number, candidates: ReadonlyArray<NodeAddress>): NodeAddress;
+    rebalance(currentShards: ReadonlyMap<string, ReadonlySet<number>>, candidates: ReadonlyArray<NodeAddress>, rebalanceInProgress: ReadonlySet<number>): Set<number>;
+}
+/**
+ * Pick the candidate currently hosting the fewest shards, breaking ties by
+ * address order.  Over time this converges to a balanced distribution even
+ * if the candidate set has changed repeatedly.
+ *
+ * @param rebalanceThreshold Minimum difference between the most- and least-loaded
+ *        nodes before any shards are moved.  Avoids thrashing.
+ * @param maxSimultaneousRebalance Cap on how many shards move in a single
+ *        rebalance round.
+ */
+export declare class LeastShardAllocationStrategy implements AllocationStrategy {
+    readonly rebalanceThreshold: number;
+    readonly maxSimultaneousRebalance: number;
+    constructor(rebalanceThreshold?: number, maxSimultaneousRebalance?: number);
+    allocate(_shardId: number, candidates: ReadonlyArray<NodeAddress>, currentShards: ReadonlyMap<string, ReadonlySet<number>>): NodeAddress;
+    rebalance(currentShards: ReadonlyMap<string, ReadonlySet<number>>, candidates: ReadonlyArray<NodeAddress>, rebalanceInProgress: ReadonlySet<number>): Set<number>;
+}
+//# sourceMappingURL=AllocationStrategy.d.ts.map

package/dist/cluster/sharding/AllocationStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AllocationStrategy.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/AllocationStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,WAAW,CAAC,EAAE,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,WAAW,CAAC;IAExI;;;;OAIG;IACH,SAAS,CACP,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,EACvD,UAAU,EAAE,aAAa,CAAC,WAAW,CAAC,EACtC,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,GACvC,GAAG,CAAC,MAAM,CAAC,CAAC;CAChB;AAID;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,WAAW;IAM9E,SAAS,CACP,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,EACvD,UAAU,EAAE,aAAa,CAAC,WAAW,CAAC,EACtC,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,GACvC,GAAG,CAAC,MAAM,CAAC;CAcf;AAED;;;;;;;;;GASG;AACH,qBAAa,4BAA6B,YAAW,kBAAkB;IAEnE,QAAQ,CAAC,kBAAkB,EAAE,MAAM;IACnC,QAAQ,CAAC,wBAAwB,EAAE,MAAM;gBADhC,kBAAkB,GAAE,MAAU,EAC9B,wBAAwB,GAAE,MAAU;IAG/C,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,aAAa,CAAC,WAAW,CAAC,EACtC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,GACtD,WAAW;IAad,SAAS,CACP,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,EACvD,UAAU,EAAE,aAAa,CAAC,WAAW,CAAC,EACtC,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,GACvC,GAAG,CAAC,MAAM,CAAC;CA6Bf"}

package/dist/cluster/sharding/AllocationStrategy.js

@@ -0,0 +1,95 @@
+/* --------------------------- Built-in strategies --------------------------- */
+/**
+ * Hash-based: allocate by modulo on the sorted candidate list.  Simple,
+ * deterministic, minimal rebalance behaviour (only moves shards when the
+ * candidate set changes).
+ */
+export class HashAllocationStrategy {
+    allocate(shardId, candidates) {
+        if (candidates.length === 0)
+            throw new Error('HashAllocationStrategy: no candidates');
+        const sorted = [...candidates].sort((a, b) => a.compareTo(b));
+        return sorted[shardId % sorted.length];
+    }
+    rebalance(currentShards, candidates, rebalanceInProgress) {
+        // Find shards whose hashed owner is no longer their actual owner.
+        const sorted = [...candidates].sort((a, b) => a.compareTo(b));
+        if (sorted.length === 0)
+            return new Set();
+        const out = new Set();
+        for (const [addrStr, shards] of currentShards) {
+            for (const shardId of shards) {
+                if (rebalanceInProgress.has(shardId))
+                    continue;
+                const desired = sorted[shardId % sorted.length];
+                if (desired.toString() !== addrStr)
+                    out.add(shardId);
+            }
+        }
+        return out;
+    }
+}
+/**
+ * Pick the candidate currently hosting the fewest shards, breaking ties by
+ * address order.  Over time this converges to a balanced distribution even
+ * if the candidate set has changed repeatedly.
+ *
+ * @param rebalanceThreshold Minimum difference between the most- and least-loaded
+ *        nodes before any shards are moved.  Avoids thrashing.
+ * @param maxSimultaneousRebalance Cap on how many shards move in a single
+ *        rebalance round.
+ */
+export class LeastShardAllocationStrategy {
+    rebalanceThreshold;
+    maxSimultaneousRebalance;
+    constructor(rebalanceThreshold = 1, maxSimultaneousRebalance = 3) {
+        this.rebalanceThreshold = rebalanceThreshold;
+        this.maxSimultaneousRebalance = maxSimultaneousRebalance;
+    }
+    allocate(_shardId, candidates, currentShards) {
+        if (candidates.length === 0)
+            throw new Error('LeastShardAllocationStrategy: no candidates');
+        let best = candidates[0];
+        let bestLoad = currentShards.get(best.toString())?.size ?? 0;
+        for (const c of candidates) {
+            const load = currentShards.get(c.toString())?.size ?? 0;
+            if (load < bestLoad || (load === bestLoad && c.compareTo(best) < 0)) {
+                best = c;
+                bestLoad = load;
+            }
+        }
+        return best;
+    }
+    rebalance(currentShards, candidates, rebalanceInProgress) {
+        const out = new Set();
+        if (candidates.length < 2)
+            return out;
+        // Consider only candidate loads (others may be down or pre-Up).
+        const loads = candidates.map(c => [
+            c.toString(),
+            currentShards.get(c.toString())?.size ?? 0,
+            currentShards.get(c.toString()) ?? new Set(),
+        ]);
+        loads.sort((a, b) => a[1] - b[1]);
+        const [, min] = loads[0];
+        const [, max] = loads[loads.length - 1];
+        if (max - min < this.rebalanceThreshold)
+            return out;
+        // Drain from the busiest node(s) until budget is exhausted.
+        let remaining = this.maxSimultaneousRebalance;
+        for (let i = loads.length - 1; i >= 0 && remaining > 0; i--) {
+            const load = loads[i][1];
+            if (load - min < this.rebalanceThreshold)
+                break;
+            for (const shardId of loads[i][2]) {
+                if (rebalanceInProgress.has(shardId))
+                    continue;
+                out.add(shardId);
+                if (--remaining <= 0)
+                    break;
+            }
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=AllocationStrategy.js.map

package/dist/cluster/sharding/AllocationStrategy.js.map

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

package/dist/cluster/sharding/CassandraRememberEntitiesStore.d.ts

@@ -0,0 +1,77 @@
+import type { CassandraClientLike, CassandraConnection } from '../../persistence/journals/CassandraClient.js';
+import type { RememberEntitiesStore, RememberEvent } from './RememberEntitiesStore.js';
+/**
+ * Cassandra-backed `RememberEntitiesStore` for `ClusterSharding` (#84)
+ * — the natural complement to the existing `JournalRememberEntitiesStore`
+ * for deployments using Cassandra/Scylla as their event journal.
+ *
+ * **Schema design.**  State-based, not event-sourced.  Each known
+ * (type, shard, entity) triple lives as a single row with a
+ * `started_at` timestamp; `stopped` events translate into a row
+ * delete, `started` events into an upsert.  This is materially
+ * cheaper to reload than the journal-backed implementation (one
+ * partition scan vs. replaying every lifecycle event ever recorded
+ * for the type) at the cost of losing history — but the
+ * coordinator only needs the **current** entity set.
+ *
+ * **Partition layout.**  Partition key is `type_name`; clustering
+ * key is `(shard_id, entity_id)`.  Every entity for a given sharded
+ * type lands in one partition.  Acceptable for typical workloads
+ * (thousands of entities per type, fits comfortably in a single
+ * Cassandra partition); for very large entity sets, switch to the
+ * journal-backed store or split the partition by `shard_id` (the
+ * standard Cassandra "wide-row → composite-key" workaround).
+ *
+ * **`clear` semantics.**  Issues `DELETE FROM tbl WHERE type_name = ?`
+ * — a whole-partition delete, atomic in Cassandra.  Scoping resets to
+ * one type at a time matches `JournalRememberEntitiesStore`.
+ *
+ * **Replay shape.**  `load` returns synthetic `'started'` events for
+ * every row currently in the partition.  No `'stopped'` events are
+ * emitted because they were applied via DELETE at write time —
+ * `ShardCoordinator` reapplies the result to its in-memory map and
+ * arrives at the same `entitiesPerShard` view the event-replay
+ * variant produces.
+ */
+export interface CassandraRememberEntitiesStoreOptions extends CassandraConnection {
+    /** Table for the remember-entities state.  Default: `remember_entities`. */
+    readonly table?: string;
+    /** Auto-create the table on first use.  Default: `true`. */
+    readonly autoCreateTables?: boolean;
+    /**
+     * Inject a pre-built CQL client.  When omitted, the store
+     * instantiates its own (via `cassandra-driver`) — but typical
+     * deployments share one client across journal + snapshot store +
+     * remember-entities, so passing the existing one in is the
+     * recommended pattern.
+     */
+    readonly client?: CassandraClientLike;
+}
+export declare class CassandraRememberEntitiesStore implements RememberEntitiesStore {
+    private readonly options;
+    private client;
+    private readonly ownsClient;
+    private started;
+    private stopped;
+    constructor(options: CassandraRememberEntitiesStoreOptions);
+    start(): Promise<void>;
+    append(typeName: string, event: RememberEvent): Promise<void>;
+    load(typeName: string): Promise<RememberEvent[]>;
+    clear(typeName: string): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private get table();
+    private qualified;
+}
+/**
+ * DDL for the remember-entities state table populated by
+ * {@link CassandraRememberEntitiesStore} (#84).  Returned as a
+ * runnable CQL string so operators applying schemas by hand can
+ * mirror the store's exact layout — same pattern as
+ * {@link tagIndexDdl} from #44.
+ */
+export declare function rememberEntitiesDdl(args: {
+    readonly keyspace: string;
+    readonly table?: string;
+}): string;
+//# sourceMappingURL=CassandraRememberEntitiesStore.d.ts.map

package/dist/cluster/sharding/CassandraRememberEntitiesStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CassandraRememberEntitiesStore.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/CassandraRememberEntitiesStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AAE9G,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,qCAAsC,SAAQ,mBAAmB;IAChF,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;CACvC;AASD,qBAAa,8BAA+B,YAAW,qBAAqB;IAC1E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAChE,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,qCAAqC;IAMpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBtB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB7D,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAehD,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAStC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAUd,aAAa;IAK3B,OAAO,KAAK,KAAK,GAAgE;IAEjF,OAAO,CAAC,SAAS;CAGlB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAST"}

package/dist/cluster/sharding/CassandraRememberEntitiesStore.js

@@ -0,0 +1,98 @@
+import { createCassandraClient, keyspaceDdl } from '../../persistence/journals/CassandraClient.js';
+export class CassandraRememberEntitiesStore {
+    options;
+    client;
+    ownsClient;
+    started = false;
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+        this.client = options.client ?? undefined;
+        this.ownsClient = !options.client;
+    }
+    async start() {
+        if (this.started)
+            return;
+        if (this.ownsClient && !this.client) {
+            this.client = await createCassandraClient(this.options);
+        }
+        await this.client.connect();
+        if (this.options.autoCreateKeyspace) {
+            await this.client.execute(keyspaceDdl(this.options));
+        }
+        if (this.options.autoCreateTables ?? true) {
+            await this.client.execute(rememberEntitiesDdl({
+                keyspace: this.options.keyspace,
+                table: this.options.table,
+            }));
+        }
+        this.started = true;
+    }
+    async append(typeName, event) {
+        await this.ensureStarted();
+        if (event.kind === 'started') {
+            // Upsert — the same `(type, shard, entity)` re-starting overwrites
+            // the previous `started_at` with a fresh timestamp.  The coordinator
+            // only ever calls `'started'` once per entity per lifecycle, but
+            // re-runs after a coordinator crash MAY emit duplicates and the
+            // upsert handles them idempotently.
+            await this.client.execute(`INSERT INTO ${this.qualified()} (type_name, shard_id, entity_id, started_at) VALUES (?, ?, ?, ?)`, [typeName, event.shardId, event.entityId, Date.now()], { prepare: true });
+            return;
+        }
+        // 'stopped' — point delete on the full primary key.
+        await this.client.execute(`DELETE FROM ${this.qualified()} WHERE type_name = ? AND shard_id = ? AND entity_id = ?`, [typeName, event.shardId, event.entityId], { prepare: true });
+    }
+    async load(typeName) {
+        await this.ensureStarted();
+        const res = await this.client.execute(`SELECT type_name, shard_id, entity_id, started_at FROM ${this.qualified()} WHERE type_name = ?`, [typeName], { prepare: true });
+        const rows = res.rows;
+        return rows.map((r) => ({
+            kind: 'started',
+            shardId: Number(r.shard_id),
+            entityId: r.entity_id,
+        }));
+    }
+    async clear(typeName) {
+        await this.ensureStarted();
+        await this.client.execute(`DELETE FROM ${this.qualified()} WHERE type_name = ?`, [typeName], { prepare: true });
+    }
+    async close() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.ownsClient && this.started) {
+            try {
+                await this.client.shutdown();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /* ============================== internals ============================== */
+    async ensureStarted() {
+        if (this.started)
+            return;
+        await this.start();
+    }
+    get table() { return this.options.table ?? 'remember_entities'; }
+    qualified() {
+        return `${this.options.keyspace}.${this.table}`;
+    }
+}
+/**
+ * DDL for the remember-entities state table populated by
+ * {@link CassandraRememberEntitiesStore} (#84).  Returned as a
+ * runnable CQL string so operators applying schemas by hand can
+ * mirror the store's exact layout — same pattern as
+ * {@link tagIndexDdl} from #44.
+ */
+export function rememberEntitiesDdl(args) {
+    const table = args.table ?? 'remember_entities';
+    return `CREATE TABLE IF NOT EXISTS ${args.keyspace}.${table} (`
+        + ` type_name text,`
+        + ` shard_id int,`
+        + ` entity_id text,`
+        + ` started_at bigint,`
+        + ` PRIMARY KEY ((type_name), shard_id, entity_id)`
+        + ` ) WITH CLUSTERING ORDER BY (shard_id ASC, entity_id ASC)`;
+}
+//# sourceMappingURL=CassandraRememberEntitiesStore.js.map

package/dist/cluster/sharding/CassandraRememberEntitiesStore.js.map

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

package/dist/cluster/sharding/ClusterSharding.d.ts

@@ -0,0 +1,116 @@
+import type { ActorRef } from '../../ActorRef.js';
+import type { ActorSystem } from '../../ActorSystem.js';
+import type { Lease } from '../../coordination/Lease.js';
+import type { Cluster } from '../Cluster.js';
+import { AllocationStrategy } from './AllocationStrategy.js';
+import type { CoordinatorStateStore } from './CoordinatorState.js';
+import { type RememberEntitiesStore } from './RememberEntitiesStore.js';
+import { type ShardingSettings } from './ShardRegion.js';
+import { isShardingMessage } from './ShardingProtocol.js';
+export interface StartSettings<TMsg> extends ShardingSettings<TMsg> {
+    /** Strategy the coordinator uses to allocate and rebalance shards. */
+    readonly allocationStrategy?: AllocationStrategy;
+    /** Gap between coordinator-driven rebalance passes. */
+    readonly rebalanceIntervalMs?: number;
+    /** Time to wait for HandOffComplete before force-reallocating. */
+    readonly handOffTimeoutMs?: number;
+    /**
+     * Optional split-brain protection for the coordinator.  When set,
+     * the elected leader's coordinator must hold the lease before it
+     * processes shard messages — under a network partition that
+     * produces two leader views, only the side that successfully
+     * acquires the lease ever issues `AllocateShard` / `HandOff`
+     * directives.  See `ShardCoordinatorSettings.lease`.
+     */
+    readonly lease?: Lease;
+    /** Retry interval for `lease.acquire()` after a failed attempt.  Default: 5 s. */
+    readonly acquireRetryIntervalMs?: number;
+    /**
+     * Optional persistence backend for the entity registry — relevant
+     * only when `rememberEntities: true`.  When omitted (and
+     * `rememberEntities: true`), the default
+     * `JournalRememberEntitiesStore` is auto-instantiated using the
+     * Journal from the system's `PersistenceExtension`, so a full
+     * cluster cold-start no longer loses the registry.  Set to a
+     * custom impl to plug in a separate store.
+     *
+     * Pass `null` to opt out of persistence entirely (registry stays
+     * in-memory only — the v1 behaviour).
+     */
+    readonly rememberEntitiesStore?: RememberEntitiesStore | null;
+    /**
+     * Optional persistence backend for the coordinator's allocation
+     * state (`regions` + `shardHome`).  When set, a new leader
+     * elected after the previous leader's failure can seed its
+     * coordinator from the snapshot instead of running
+     * `tryAllocate` from scratch — saves a brief reallocation storm
+     * at thousands-of-shards scale.
+     *
+     * Unlike `rememberEntitiesStore`, ClusterSharding does NOT
+     * auto-instantiate this — the user must explicitly pass a store
+     * (typically `new DistributedDataCoordinatorStateStore(dd, ...)`).
+     * Without it, the v1 rebuild-from-Register behaviour is preserved.
+     */
+    readonly coordinatorStateStore?: CoordinatorStateStore;
+}
+/**
+ * User-facing entry point.  Attaches to an ActorSystem + Cluster pair and
+ * lets you start a sharded region for each entity type.  A `ShardCoordinator`
+ * is spawned lazily on every node; only the one hosted by the current
+ * cluster leader is active — the rest act as warm standbys.
+ */
+export declare class ClusterSharding {
+    readonly system: ActorSystem;
+    readonly cluster: Cluster;
+    private readonly regionsByPath;
+    private readonly coordinators;
+    private constructor();
+    private static instances;
+    static get(system: ActorSystem, cluster: Cluster): ClusterSharding;
+    /**
+     * Start a sharded region for a type.  Three calling shapes:
+     *
+     * ```ts
+     * // Shorthand: pass the entity class.  Framework wraps it with Props.create.
+     * sharding.start('counter', CounterEntity, {
+     *   extractEntityId: (msg) => msg.id,
+     * });
+     *
+     * // Shorthand: pass a factory.  Useful for closures / DI / no-arg new.
+     * sharding.start('cart', () => new CartEntity(deps), {
+     *   extractEntityId: (msg) => msg.entityId,
+     * });
+     *
+     * // Full-form: explicit Props + all settings (unchanged).
+     * sharding.start({
+     *   typeName: 'counter',
+     *   entityProps: Props.create(() => new CounterEntity()),
+     *   extractEntityId: (msg) => msg.id,
+     * });
+     * ```
+     */
+    start<TMsg>(settings: StartSettings<TMsg>): ActorRef<TMsg>;
+    start<TMsg>(typeName: string, entity: (new () => import('../../Actor.js').Actor<TMsg>) | (() => import('../../Actor.js').Actor<TMsg>), opts: Omit<StartSettings<TMsg>, 'typeName' | 'entityProps'>): ActorRef<TMsg>;
+    /** @internal — wrap the shorthand entity arg into a Props + assemble full settings. */
+    private buildSettingsFromShorthand;
+    /** Start a proxy region — routes to the cluster but never hosts entities. */
+    startProxy<TMsg>(settings: Omit<StartSettings<TMsg>, 'proxy'>): ActorRef<TMsg>;
+    private ensureCoordinator;
+    /**
+     * Resolve the `rememberEntitiesStore` for a sharded type:
+     *
+     *   - User passed `null`           → keep registry in-memory only.
+     *   - User passed an instance      → use it as-is.
+     *   - rememberEntities=false       → no persistence regardless.
+     *   - rememberEntities=true (default path) → auto-instantiate
+     *     `JournalRememberEntitiesStore` from the system's persistence
+     *     extension so the registry survives cluster cold-starts
+     *     without the user wiring anything up.
+     */
+    private resolveRememberEntitiesStore;
+    private typeNameFromCoordinatorPath;
+    private findRegionByType;
+    private dispatchEnvelope;
+}
+export { isShardingMessage };
+//# sourceMappingURL=ClusterSharding.d.ts.map

package/dist/cluster/sharding/ClusterSharding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterSharding.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/ClusterSharding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAGzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAA0B,MAAM,yBAAyB,CAAC;AACrF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,WAAW,aAAa,CAAC,IAAI,CAAE,SAAQ,gBAAgB,CAAC,IAAI,CAAC;IACjE,sEAAsE;IACtE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD,uDAAuD;IACvD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC9D;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;CACxD;AAED;;;;;GAKG;AACH,qBAAa,eAAe;aAKR,MAAM,EAAE,WAAW;aACnB,OAAO,EAAE,OAAO;IALlC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;IACtE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwC;IAErE,OAAO;IAOP,OAAO,CAAC,MAAM,CAAC,SAAS,CAA+C;IAEvE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,eAAe;IAQlE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC1D,KAAK,CAAC,IAAI,EACR,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,UAAU,OAAO,gBAAgB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,OAAO,gBAAgB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,EACvG,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC,GAC1D,QAAQ,CAAC,IAAI,CAAC;IA6BjB,uFAAuF;IACvF,OAAO,CAAC,0BAA0B;IAoBlC,6EAA6E;IAC7E,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC;IAM9E,OAAO,CAAC,iBAAiB;IA2BzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,4BAA4B;IAUpC,OAAO,CAAC,2BAA2B;IAKnC,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,gBAAgB;CAQzB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}