actor-ts 0.9.0

package/dist/cluster/sharding/ShardedDaemonProcess.js

@@ -0,0 +1,107 @@
+import { match, P } from 'ts-pattern';
+import { Actor } from '../../Actor.js';
+import { Props } from '../../Props.js';
+import { LeaderChanged, MemberRemoved } from '../ClusterEvents.js';
+import { LeastShardAllocationStrategy } from './AllocationStrategy.js';
+import { ClusterSharding } from './ClusterSharding.js';
+const WAKEUP = { t: 'sharded-daemon.wakeup' };
+/**
+ * Starts exactly N named daemon actors spread across the cluster.  Built on
+ * top of ClusterSharding: each daemon becomes an entity, each entity gets
+ * its own shard via a 1-to-1 allocation, and `rememberEntities` ensures the
+ * daemons respawn after a node failure.
+ *
+ * The allocation strategy defaults to `LeastShardAllocationStrategy` so
+ * daemons spread evenly over nodes.  Every daemon index receives a
+ * synthetic "wake-up" message at init time which causes the sharding
+ * machinery to materialize it on the node the coordinator chose.
+ */
+export class ShardedDaemonProcess {
+    static init(system, cluster, settings) {
+        const sharding = ClusterSharding.get(system, cluster);
+        const region = sharding.start({
+            typeName: `daemon-${settings.name}`,
+            entityProps: Props.create(() => new DaemonHost(settings.behaviorFor)),
+            extractEntityId: (env) => String(env.index),
+            extractEntityMessage: (env) => env.body,
+            numShards: settings.numDaemons,
+            role: settings.role,
+            rememberEntities: true,
+            allocationStrategy: new LeastShardAllocationStrategy(),
+        });
+        // Wake every daemon so the coordinator allocates a shard and the host
+        // actor's preStart runs.  Afterwards rememberEntities keeps them alive.
+        const wakeAll = () => {
+            for (let i = 0; i < settings.numDaemons; i++) {
+                region.tell({ index: i, body: WAKEUP });
+            }
+        };
+        queueMicrotask(wakeAll);
+        // Re-wake when the cluster topology changes — this lets the region
+        // re-resolve homes for any orphaned shards after a node left, without
+        // waiting for the next user message to trigger the lookup.  Full
+        // respawn of entities that lived on a departed node is a function of
+        // ShardCoordinator's rebalance + rememberEntities path; this hook just
+        // makes sure the SDP-owned messages keep flowing.
+        const unsubscribe = cluster.subscribe((evt) => match(evt)
+            .with(P.union(P.instanceOf(LeaderChanged), P.instanceOf(MemberRemoved)), () => { setTimeout(wakeAll, 100); })
+            .otherwise(() => { }));
+        // Periodic liveness backstop — fires even when no cluster events do,
+        // so any wake-up that got lost in transit (rare, but possible during
+        // brief partition + heal cycles) gets retried.
+        const livenessIntervalMs = settings.livenessIntervalMs ?? 30_000;
+        let livenessTimer = null;
+        if (livenessIntervalMs > 0) {
+            livenessTimer = system.scheduler.scheduleAtFixedRateFn(livenessIntervalMs, livenessIntervalMs, wakeAll);
+        }
+        let stopped = false;
+        return {
+            region,
+            tell(index, message) {
+                region.tell({ index, body: message });
+            },
+            stop() {
+                if (stopped)
+                    return;
+                stopped = true;
+                livenessTimer?.cancel();
+                unsubscribe();
+            },
+        };
+    }
+}
+/**
+ * Host actor spawned by ShardRegion for each daemon index.  On first start
+ * it derives its daemon index from its actor name and constructs the real
+ * user Actor as a child.  All user messages are forwarded to that child.
+ */
+class DaemonHost extends Actor {
+    behaviorFor;
+    inner = null;
+    constructor(behaviorFor) {
+        super();
+        this.behaviorFor = behaviorFor;
+    }
+    preStart() {
+        const index = indexFromEntityName(this.context.path.name);
+        const props = this.behaviorFor(index);
+        this.inner = this.context.spawn(props, 'daemon');
+    }
+    onReceive(msg) {
+        // ShardRegion uses `extractEntityMessage` to unwrap the envelope before
+        // delivery, so `msg` here is actually the `body` field of the envelope.
+        if (isWakeup(msg))
+            return; // already awake — preStart ran
+        this.inner?.tell(msg);
+    }
+}
+function indexFromEntityName(name) {
+    // Names are set by ShardRegion as `entity-<entityId>` where entityId is
+    // the stringified daemon index (see extractEntityId above).
+    const m = name.match(/^entity-(\d+)$/);
+    return m ? parseInt(m[1], 10) : 0;
+}
+function isWakeup(x) {
+    return !!x && typeof x === 'object' && x.t === 'sharded-daemon.wakeup';
+}
+//# sourceMappingURL=ShardedDaemonProcess.js.map

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

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

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

@@ -0,0 +1,92 @@
+import type { NodeAddressData } from '../NodeAddress.js';
+/**
+ * Message types exchanged between ShardRegions and the ShardCoordinator.
+ * They travel as plain actor messages (delivered locally or over the wire
+ * as EnvelopeMsg.body) so the discriminator is a string `$t` property.
+ */
+export interface RegisterRegion {
+    readonly $t: 'sharding.Register';
+    readonly region: string;
+    readonly node: NodeAddressData;
+    readonly proxy: boolean;
+    readonly hostedShards: number[];
+}
+export interface RegisterAck {
+    readonly $t: 'sharding.RegisterAck';
+    readonly coordinator: string;
+}
+export interface GetShardHome {
+    readonly $t: 'sharding.GetShardHome';
+    readonly shardId: number;
+    readonly requester: string;
+    readonly requesterNode: NodeAddressData;
+}
+export interface ShardHome {
+    readonly $t: 'sharding.ShardHome';
+    readonly shardId: number;
+    readonly region: string;
+    readonly node: NodeAddressData;
+}
+export interface BeginHandOff {
+    readonly $t: 'sharding.BeginHandOff';
+    readonly shardId: number;
+}
+export interface BeginHandOffAck {
+    readonly $t: 'sharding.BeginHandOffAck';
+    readonly shardId: number;
+}
+export interface HandOff {
+    readonly $t: 'sharding.HandOff';
+    readonly shardId: number;
+}
+export interface HandOffComplete {
+    readonly $t: 'sharding.HandOffComplete';
+    readonly shardId: number;
+    readonly region: string;
+    readonly node: NodeAddressData;
+}
+export interface RegionTerminated {
+    readonly $t: 'sharding.RegionTerminated';
+    readonly region: string;
+    readonly node: NodeAddressData;
+}
+export interface EntityStarted {
+    readonly $t: 'sharding.EntityStarted';
+    readonly shardId: number;
+    readonly entityId: string;
+}
+export interface EntityStopped {
+    readonly $t: 'sharding.EntityStopped';
+    readonly shardId: number;
+    readonly entityId: string;
+}
+export interface RememberedEntities {
+    readonly $t: 'sharding.RememberedEntities';
+    readonly shardId: number;
+    readonly entityIds: string[];
+}
+/**
+ * Wraps a user message forwarded between ShardRegions, carrying the
+ * information needed to route a reply back to the original asker.
+ *
+ * The origin region (where the ask started) stores the real sender keyed
+ * by `correlationId` and forwards this envelope; the receiving region
+ * materialises a synthetic sender ref bound to that correlationId so any
+ * reply from the entity flows back as a `ShardReply`.
+ */
+export interface ShardEnvelope {
+    readonly $t: 'sharding.Envelope';
+    readonly message: unknown;
+    readonly originNode: NodeAddressData | null;
+    readonly originRegion: string | null;
+    readonly correlationId: number | null;
+}
+/** Reply counterpart to {@link ShardEnvelope} — delivers a response to the asker. */
+export interface ShardReply {
+    readonly $t: 'sharding.Reply';
+    readonly correlationId: number;
+    readonly message: unknown;
+}
+export type ShardingMessage = RegisterRegion | RegisterAck | GetShardHome | ShardHome | BeginHandOff | BeginHandOffAck | HandOff | HandOffComplete | RegionTerminated | EntityStarted | EntityStopped | RememberedEntities | ShardEnvelope | ShardReply;
+export declare function isShardingMessage(msg: unknown): msg is ShardingMessage;
+//# sourceMappingURL=ShardingProtocol.d.ts.map

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

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

package/dist/cluster/sharding/ShardingProtocol.js

@@ -0,0 +1,7 @@
+export function isShardingMessage(msg) {
+    return typeof msg === 'object'
+        && msg !== null
+        && typeof msg.$t === 'string'
+        && msg.$t.startsWith('sharding.');
+}
+//# sourceMappingURL=ShardingProtocol.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ShardingProtocol.js","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardingProtocol.ts"],"names":[],"mappings":"AAyHA,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,OAAO,GAAG,KAAK,QAAQ;WACzB,GAAG,KAAK,IAAI;WACZ,OAAQ,GAAwB,CAAC,EAAE,KAAK,QAAQ;WAC/C,GAAsB,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAC1D,CAAC"}

package/dist/cluster/singleton/ClusterSingleton.d.ts

@@ -0,0 +1,59 @@
+import type { ActorRef } from '../../ActorRef.js';
+import type { ActorSystem } from '../../ActorSystem.js';
+import type { Lease } from '../../coordination/Lease.js';
+import { type ExtensionId } from '../../Extension.js';
+import { Props } from '../../Props.js';
+import type { Cluster } from '../Cluster.js';
+import { type Option } from '../../util/Option.js';
+import { ClusterSingletonProxy } from './ClusterSingletonProxy.js';
+export interface StartSingletonSettings<T> {
+    /** Logical name for this singleton — used in the manager/child actor path. */
+    readonly typeName: string;
+    /** Props used to construct the singleton on the leader. */
+    readonly props: Props<T>;
+    /** If set, only nodes carrying this role tag will host the singleton. */
+    readonly role?: string;
+    /**
+     * Optional split-brain protection.  When provided, the elected
+     * leader's manager calls `lease.acquire()` before spawning the
+     * singleton — so a partition that produces two oldest views still
+     * only ever spawns the singleton on the side that holds the lease.
+     * The manager subscribes to `lease.onLost(reason)` and stops the
+     * child if ownership is revoked mid-flight.
+     *
+     * Without a lease the manager keeps its current sync behaviour:
+     * spawn the moment cluster gossip says we're leader, no external
+     * arbitration.
+     */
+    readonly lease?: Lease;
+    /**
+     * How often to retry `lease.acquire()` after a failed attempt
+     * (another holder owns it, transient backend error, etc.).
+     * Default: `5_000` ms.  Ignored if no lease is provided.
+     */
+    readonly acquireRetryIntervalMs?: number;
+}
+export interface SingletonHandle<T> {
+    /** Location-transparent ActorRef — tell here, the leader's instance receives. */
+    readonly proxy: ClusterSingletonProxy<T>;
+    /** Local manager — stopping it takes this node out of rotation. */
+    readonly manager: ActorRef;
+    /** Stop both proxy and local manager. */
+    stop(): void;
+}
+/**
+ * Extension registered on the ActorSystem that manages all
+ * ClusterSingletons declared in the process.  Use
+ * `system.extension(ClusterSingletonId).start(cluster, ...)` to materialize
+ * one; subsequent calls with the same typeName return the same handle.
+ */
+export declare class ClusterSingleton {
+    private readonly system;
+    private handles;
+    constructor(system: ActorSystem);
+    start<T>(cluster: Cluster, settings: StartSingletonSettings<T>): SingletonHandle<T>;
+    /** Look up a previously-started singleton by typeName. */
+    get<T>(typeName: string): Option<SingletonHandle<T>>;
+}
+export declare const ClusterSingletonId: ExtensionId<ClusterSingleton>;
+//# sourceMappingURL=ClusterSingleton.d.ts.map

package/dist/cluster/singleton/ClusterSingleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterSingleton.d.ts","sourceRoot":"","sources":["../../../src/cluster/singleton/ClusterSingleton.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;AACzD,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAMjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACzC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,yCAAyC;IACzC,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAEf,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,OAAO,CAAC,OAAO,CAA+C;gBACjC,MAAM,EAAE,WAAW;IAEhD,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IA2CnF,0DAA0D;IAC1D,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CAGrD;AAED,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,gBAAgB,CAG5D,CAAC"}

package/dist/cluster/singleton/ClusterSingleton.js

@@ -0,0 +1,63 @@
+import { extensionId } from '../../Extension.js';
+import { Props } from '../../Props.js';
+import { fromNullable } from '../../util/Option.js';
+import { ClusterSingletonManager, singletonManagerPath, } from './ClusterSingletonManager.js';
+import { ClusterSingletonProxy } from './ClusterSingletonProxy.js';
+/**
+ * Extension registered on the ActorSystem that manages all
+ * ClusterSingletons declared in the process.  Use
+ * `system.extension(ClusterSingletonId).start(cluster, ...)` to materialize
+ * one; subsequent calls with the same typeName return the same handle.
+ */
+export class ClusterSingleton {
+    system;
+    handles = new Map();
+    constructor(system) {
+        this.system = system;
+    }
+    start(cluster, settings) {
+        const existing = this.handles.get(settings.typeName);
+        if (existing)
+            return existing;
+        // Register the envelope handler *before* spawning the manager actor so
+        // remote proxies that fire during the brief spawn window don't drop.
+        // The handler enqueues via the not-yet-existing ref — we close over the
+        // same variable and assign below.
+        let managerRef = null;
+        const envelopeUnsub = cluster._registerEnvelopeHandler(singletonManagerPath(this.system.name, settings.typeName), (env) => {
+            // Route inbound envelopes through the manager's own mailbox so the
+            // manager processes them on its own dispatcher thread.
+            if (managerRef)
+                managerRef.tell({ t: 'singleton-deliver', body: env.body });
+        });
+        const managerProps = Props.create(() => {
+            const mgr = new ClusterSingletonManager({
+                cluster,
+                typeName: settings.typeName,
+                singletonProps: settings.props,
+                role: settings.role,
+                lease: settings.lease,
+                acquireRetryIntervalMs: settings.acquireRetryIntervalMs,
+            });
+            mgr._envelopeUnsub = envelopeUnsub;
+            return mgr;
+        });
+        managerRef = this.system.spawn(managerProps, `singleton-manager-${settings.typeName}`);
+        const proxy = new ClusterSingletonProxy(cluster, settings.typeName, managerRef);
+        const handle = {
+            proxy, manager: managerRef,
+            stop() {
+                proxy.stop();
+                managerRef.stop();
+            },
+        };
+        this.handles.set(settings.typeName, handle);
+        return handle;
+    }
+    /** Look up a previously-started singleton by typeName. */
+    get(typeName) {
+        return fromNullable(this.handles.get(typeName));
+    }
+}
+export const ClusterSingletonId = extensionId('actor-ts/cluster/singleton', (system) => new ClusterSingleton(system));
+//# sourceMappingURL=ClusterSingleton.js.map

package/dist/cluster/singleton/ClusterSingleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterSingleton.js","sourceRoot":"","sources":["../../../src/cluster/singleton/ClusterSingleton.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAoB,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAAE,YAAY,EAAe,MAAM,sBAAsB,CAAC;AACjE,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GAErB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAuCnE;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAEE;IADrB,OAAO,GAAG,IAAI,GAAG,EAAoC,CAAC;IAC9D,YAA6B,MAAmB;QAAnB,WAAM,GAAN,MAAM,CAAa;IAAG,CAAC;IAEpD,KAAK,CAAI,OAAgB,EAAE,QAAmC;QAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACrD,IAAI,QAAQ;YAAE,OAAO,QAA8B,CAAC;QAEpD,uEAAuE;QACvE,qEAAqE;QACrE,wEAAwE;QACxE,kCAAkC;QAClC,IAAI,UAAU,GAAa,IAA2B,CAAC;QACvD,MAAM,aAAa,GAAG,OAAO,CAAC,wBAAwB,CACpD,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,EACzD,CAAC,GAAG,EAAE,EAAE;YACN,mEAAmE;YACnE,uDAAuD;YACvD,IAAI,UAAU;gBAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,mBAAmB,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAA+B,CAAC,CAAC;QAC3G,CAAC,CACF,CAAC;QAEF,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE;YACrC,MAAM,GAAG,GAAG,IAAI,uBAAuB,CAAI;gBACzC,OAAO;gBACP,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,cAAc,EAAE,QAAQ,CAAC,KAAK;gBAC9B,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,sBAAsB,EAAE,QAAQ,CAAC,sBAAsB;aACxD,CAAC,CAAC;YACH,GAAG,CAAC,cAAc,GAAG,aAAa,CAAC;YACnC,OAAO,GAAG,CAAC;QACb,CAAC,CAAC,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,qBAAqB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QACvF,MAAM,KAAK,GAAG,IAAI,qBAAqB,CAAI,OAAO,EAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACnF,MAAM,MAAM,GAAuB;YACjC,KAAK,EAAE,OAAO,EAAE,UAAU;YAC1B,IAAI;gBACF,KAAK,CAAC,IAAI,EAAE,CAAC;gBACb,UAAU,CAAC,IAAI,EAAE,CAAC;YACpB,CAAC;SACF,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAkC,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,0DAA0D;IAC1D,GAAG,CAAI,QAAgB;QACrB,OAAO,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAmC,CAAC,CAAC;IACpF,CAAC;CACF;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAkC,WAAW,CAC1E,4BAA4B,EAC5B,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,CACzC,CAAC"}

package/dist/cluster/singleton/ClusterSingletonManager.d.ts

@@ -0,0 +1,116 @@
+import { Actor } from '../../Actor.js';
+import type { Lease } from '../../coordination/Lease.js';
+import type { Props } from '../../Props.js';
+import { Terminated } from '../../SystemMessages.js';
+import type { Cluster } from '../Cluster.js';
+/**
+ * Path at which every node hosts its ClusterSingletonManager for a given
+ * singleton typeName.  Used by the proxy/envelope layer to address the
+ * manager on whichever node is currently the leader.
+ */
+export declare function singletonManagerPath(systemName: string, typeName: string): string;
+/** Internal delivery wrapper — body is the user's typed message. */
+export interface SingletonDeliver {
+    readonly t: 'singleton-deliver';
+    readonly body: unknown;
+}
+/**
+ * The lease-aware path uses internal events instead of inline awaits so
+ * cluster-event triggers can't interleave their `reconcile` calls with
+ * an in-flight `lease.acquire()`.  Every state transition arrives as a
+ * single message in this manager's own mailbox.
+ */
+type ManagerEvent = {
+    t: 'reconcile';
+} | {
+    t: 'lease-acquire-result';
+    got: boolean;
+    error?: Error;
+} | {
+    t: 'lease-lost';
+    reason: string;
+} | {
+    t: 'acquire-retry';
+};
+type Inbox = SingletonDeliver | ManagerEvent | Terminated;
+export interface ClusterSingletonManagerSettings<T> {
+    readonly cluster: Cluster;
+    /** Logical name for this singleton; also used as the child-actor name. */
+    readonly typeName: string;
+    /** How to construct the singleton actor.  Only instantiated on the leader. */
+    readonly singletonProps: Props<T>;
+    /** Optional role — only nodes with this role will host the singleton. */
+    readonly role?: string;
+    /** Optional split-brain protection — see {@link StartSingletonSettings.lease}. */
+    readonly lease?: Lease;
+    /** Retry interval for `lease.acquire()` after a failed attempt.  Default: 5 s. */
+    readonly acquireRetryIntervalMs?: number;
+}
+/**
+ * Runs on every node.  Watches cluster events and (re)spawns the singleton
+ * child when this node is the cluster leader; stops the child when it is not.
+ * Remote Envelopes addressed to the singleton land here and are forwarded to
+ * the child — if the manager is not on the leader node, the envelope is
+ * dropped with a warning (the proxy shouldn't have forwarded there).
+ *
+ * **Two paths:**
+ *
+ * - **No lease (default).**  Synchronous reconcile — spawn the moment
+ *   cluster gossip says we're leader.  Same behaviour the manager has
+ *   shipped since v1.
+ * - **With lease.**  Async reconcile that gates child-spawn on
+ *   `lease.acquire()`, watches `lease.onLost(...)` for revocation, and
+ *   `release()`s on graceful handover.  All state transitions go through
+ *   the manager's own mailbox so concurrent cluster events can't race
+ *   with an in-flight acquire.
+ */
+export declare class ClusterSingletonManager<T> extends Actor<Inbox> {
+    readonly settings: ClusterSingletonManagerSettings<T>;
+    private child;
+    /**
+     * The previous child while it is mid-stop.  We watch every child we
+     * spawn (see `spawn()`), and when leadership flips we move
+     * `this.child` here, send `PoisonPill`, and wait for the
+     * `Terminated` system message before allowing another `spawn()`.
+     * Without this, a fast leader-flap (or two cluster events back-to-
+     * back from `handleLeave`) reaches `spawn` while the previous
+     * child cell is still in the parent's `_children` map — the new
+     * spawn fails with "Child name 'X' is not unique".  It also avoids
+     * spawning a second user actor (e.g. a fresh `HttpIngressActor`
+     * trying to bind port 8080) before the previous one has finished
+     * `postStop` and released its resources.
+     */
+    private pendingStop;
+    private unsubCluster;
+    private unsubLeaseLost;
+    private retryTimer;
+    /** Lease lifecycle — only used when `settings.lease` is set. */
+    private leaseState;
+    /** Callback the extension hands us so we can release the envelope path on stop. */
+    _envelopeUnsub: (() => void) | null;
+    constructor(settings: ClusterSingletonManagerSettings<T>);
+    preStart(): void;
+    postStop(): Promise<void>;
+    onReceive(msg: Inbox): void | Promise<void>;
+    /**
+     * Death-watch callback for the previous singleton child.  Fires once
+     * `pendingStop` has fully terminated (postStop run, cell removed
+     * from the parent's children map).  At that point it's safe to
+     * spawn a fresh child, so we re-run the reconcile logic — if we're
+     * still the leader, a new child will be created here.
+     */
+    private handleTerminated;
+    private handleDeliver;
+    /** Sync reconcile — no lease.  Spawn / stop the child to match cluster state. */
+    private reconcileSync;
+    private handleReconcile;
+    private runAcquire;
+    private handleAcquireResult;
+    private handleLeaseLost;
+    private wantHosted;
+    private spawn;
+    private stopChild;
+    private scheduleAcquireRetry;
+}
+export {};
+//# sourceMappingURL=ClusterSingletonManager.d.ts.map

package/dist/cluster/singleton/ClusterSingletonManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterSingletonManager.d.ts","sourceRoot":"","sources":["../../../src/cluster/singleton/ClusterSingletonManager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,CAAC,EAAE,mBAAmB,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAGD;;;;;GAKG;AACH,KAAK,YAAY,GACb;IAAE,CAAC,EAAE,WAAW,CAAA;CAAE,GAClB;IAAE,CAAC,EAAE,sBAAsB,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC1D;IAAE,CAAC,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,CAAC,EAAE,eAAe,CAAA;CAAE,CAAC;AAE3B,KAAK,KAAK,GAAG,gBAAgB,GAAG,YAAY,GAAG,UAAU,CAAC;AAE1D,MAAM,WAAW,+BAA+B,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,uBAAuB,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,KAAK,CAAC;aA0B9B,QAAQ,EAAE,+BAA+B,CAAC,CAAC,CAAC;IAzBxE,OAAO,CAAC,KAAK,CAA4B;IACzC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,UAAU,CAA4B;IAE9C,gEAAgE;IAChE,OAAO,CAAC,UAAU,CAAyC;IAE3D,mFAAmF;IACnF,cAAc,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAQ;gBAEf,QAAQ,EAAE,+BAA+B,CAAC,CAAC,CAAC;IAE/D,QAAQ,IAAI,IAAI;IAwCV,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB/B,SAAS,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpD;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,aAAa;IAWrB,iFAAiF;IACjF,OAAO,CAAC,aAAa;YAYP,eAAe;YA8Bf,UAAU;IAWxB,OAAO,CAAC,mBAAmB;IA4B3B,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,KAAK;IAcb,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,oBAAoB;CAO7B"}