actor-ts 0.9.0

package/dist/cluster/Transport.js

@@ -0,0 +1,299 @@
+import { getTcpBackend, } from '../runtime/tcp/index.js';
+import { NodeAddress } from './NodeAddress.js';
+import { encodeFrame, FrameDecoder, DEFAULT_MAX_FRAME_BYTES, } from './Protocol.js';
+/**
+ * TCP-backed cluster transport.  Wire framing lives in `Protocol.ts`; the
+ * actual socket API is plugged in per runtime via `TcpBackend`
+ * (`src/runtime/tcp/`), so this class is identical on Bun, Node.js, and
+ * Deno — the differences in listen/connect/socket shape are absorbed by
+ * the adapter.
+ *
+ * Per-connection state is tracked in a `WeakMap<TcpSocketLike, Conn>` —
+ * `TcpSocketLike` is intentionally opaque and has no stash slot.
+ */
+export class TcpTransport {
+    self;
+    log;
+    tls;
+    maxFrameBytes;
+    backend = null;
+    listener = null;
+    byPeer = new Map();
+    bySocket = new WeakMap();
+    handler = () => { };
+    stopped = false;
+    constructor(self, log, 
+    /** Optional TLS configuration — when set, both listener and dialer use TLS. */
+    tls = null, 
+    /**
+     * Per-frame size cap (security).  Frames whose length-prefix
+     * exceeds this are rejected before any payload bytes are
+     * buffered — closes the 4-GiB-claim DoS vector documented on
+     * {@link FrameDecoder}.  Default: {@link DEFAULT_MAX_FRAME_BYTES}
+     * (16 MiB).  Raise it only if you genuinely send larger
+     * envelopes; the cap is per-frame, not aggregate.
+     */
+    maxFrameBytes = DEFAULT_MAX_FRAME_BYTES) {
+        this.self = self;
+        this.log = log;
+        this.tls = tls;
+        this.maxFrameBytes = maxFrameBytes;
+    }
+    setHandler(handler) { this.handler = handler; }
+    async start() {
+        this.backend = await getTcpBackend();
+        this.listener = await this.backend.listen({
+            host: this.self.host,
+            port: this.self.port,
+            tls: this.tls ?? undefined,
+            handlers: {
+                onOpen: (sock) => this.attachInbound(sock),
+                onData: (sock, chunk) => this.onData(sock, chunk),
+                onClose: (sock) => this.onClose(sock),
+                onError: (_sock, err) => this.log.warn('inbound socket error', err),
+            },
+        });
+        this.log.info(`cluster transport listening on ${this.self.host}:${this.self.port}`);
+    }
+    async shutdown() {
+        this.stopped = true;
+        for (const conn of this.byPeer.values()) {
+            try {
+                conn.socket?.end();
+            }
+            catch { /* ignore */ }
+        }
+        this.byPeer.clear();
+        if (this.listener) {
+            try {
+                await this.listener.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.listener = null;
+    }
+    send(to, msg) {
+        if (this.stopped)
+            return;
+        const conn = this.byPeer.get(to.toString()) ?? this.openOutbound(to);
+        if (conn.peer && conn.socket) {
+            conn.socket.write(encodeFrame(msg));
+        }
+        else {
+            conn.pending.push(msg); // wait for hello / hello-ack
+        }
+    }
+    disconnect(peer) {
+        const conn = this.byPeer.get(peer.toString());
+        if (!conn)
+            return;
+        try {
+            conn.socket?.end();
+        }
+        catch { /* ignore */ }
+        this.byPeer.delete(peer.toString());
+    }
+    peers() {
+        const out = [];
+        for (const conn of this.byPeer.values())
+            if (conn.peer)
+                out.push(conn.peer);
+        return out;
+    }
+    /* --------------------------- internals -------------------------------- */
+    attachInbound(sock) {
+        const conn = {
+            socket: sock,
+            peer: null,
+            decoder: new FrameDecoder(this.maxFrameBytes),
+            pending: [],
+            outbound: false,
+        };
+        this.bySocket.set(sock, conn);
+    }
+    openOutbound(to) {
+        const conn = {
+            socket: null,
+            peer: null,
+            decoder: new FrameDecoder(this.maxFrameBytes),
+            pending: [],
+            outbound: true,
+        };
+        this.byPeer.set(to.toString(), conn);
+        // Kick off the connect — when it resolves, install the socket into the
+        // pre-registered Conn so subsequent `send(...)` calls can use it.  If
+        // the connect fails, drop the Conn from byPeer so the next send()
+        // retries.
+        void (async () => {
+            try {
+                const backend = this.backend ?? (await getTcpBackend());
+                this.backend = backend;
+                const sock = await backend.connect({
+                    host: to.host,
+                    port: to.port,
+                    tls: this.tls ?? undefined,
+                    handlers: {
+                        onOpen: (s) => {
+                            // Send hello; remote will ack and we'll flush `pending` then.
+                            const hello = { t: 'hello', self: this.self.toJSON() };
+                            s.write(encodeFrame(hello));
+                        },
+                        onData: (s, chunk) => this.onData(s, chunk),
+                        onClose: (s) => this.onClose(s),
+                        onError: (_s, err) => this.log.warn(`outbound error -> ${to}`, err),
+                    },
+                });
+                conn.socket = sock;
+                this.bySocket.set(sock, conn);
+            }
+            catch (err) {
+                this.log.warn(`failed to connect to ${to}`, err);
+                this.byPeer.delete(to.toString());
+            }
+        })();
+        return conn;
+    }
+    onData(sock, chunk) {
+        let conn = this.bySocket.get(sock);
+        if (!conn) {
+            // Bun delivers `data` before `open` completes its microtask in some
+            // edge cases — attach a fresh inbound Conn lazily.
+            conn = {
+                socket: sock, peer: null, decoder: new FrameDecoder(this.maxFrameBytes),
+                pending: [], outbound: false,
+            };
+            this.bySocket.set(sock, conn);
+        }
+        let frames;
+        try {
+            frames = conn.decoder.push(chunk);
+        }
+        catch (err) {
+            // Frame-decoder rejected the input (oversized length-prefix,
+            // malformed JSON).  Drop the connection rather than letting the
+            // error propagate up the runtime's socket-data callback.
+            this.log.warn(`frame-decoder error from ${conn.peer ?? '<unknown peer>'}; closing`, err);
+            try {
+                sock.end();
+            }
+            catch { /* ignore */ }
+            this.bySocket.delete(sock);
+            if (conn.peer)
+                this.byPeer.delete(conn.peer.toString());
+            return;
+        }
+        for (const msg of frames)
+            this.onMessage(conn, msg);
+    }
+    onMessage(conn, msg) {
+        if (msg.t === 'hello') {
+            const peer = NodeAddress.fromJSON(msg.self);
+            const peerKey = peer.toString();
+            // Security: reject a duplicate-identity hello on a different
+            // socket.  Without this, a second connection claiming the
+            // same address as an existing peer would *overwrite* the
+            // byPeer map — every outbound message intended for the
+            // legitimate peer would then be routed to the attacker's
+            // socket.  First-conn-wins is also the right semantic for
+            // legitimate reconnects: the dropped conn's `onClose` runs
+            // before any new hello arrives in the common case; only a
+            // tight race causes one retry.  See {@link Transport.test}
+            // for the exploit walkthrough.
+            const existing = this.byPeer.get(peerKey);
+            if (existing && existing !== conn) {
+                this.log.warn(`hello hijack rejected: peer ${peerKey} already has an active connection; ` +
+                    `closing the new socket`);
+                try {
+                    conn.socket?.end();
+                }
+                catch { /* ignore */ }
+                this.bySocket.delete(conn.socket);
+                return;
+            }
+            conn.peer = peer;
+            this.byPeer.set(peerKey, conn);
+            const ack = { t: 'hello-ack', self: this.self.toJSON() };
+            conn.socket?.write(encodeFrame(ack));
+            return;
+        }
+        if (msg.t === 'hello-ack') {
+            const peer = NodeAddress.fromJSON(msg.self);
+            const peerKey = peer.toString();
+            const existing = this.byPeer.get(peerKey);
+            if (existing && existing !== conn) {
+                // Same defense on the outbound-handshake side: someone
+                // already owns this peer-key, we don't take it over from
+                // them.
+                this.log.warn(`hello-ack hijack rejected: peer ${peerKey} already mapped to a different conn`);
+                try {
+                    conn.socket?.end();
+                }
+                catch { /* ignore */ }
+                this.bySocket.delete(conn.socket);
+                return;
+            }
+            conn.peer = peer;
+            this.byPeer.set(peerKey, conn);
+            const buffered = conn.pending.splice(0, conn.pending.length);
+            for (const m of buffered)
+                conn.socket?.write(encodeFrame(m));
+            return;
+        }
+        if (!conn.peer) {
+            this.log.warn('received message before hello handshake', msg);
+            return;
+        }
+        this.handler(conn.peer, msg);
+    }
+    onClose(sock) {
+        const conn = this.bySocket.get(sock);
+        if (!conn)
+            return;
+        this.bySocket.delete(sock);
+        if (conn.peer)
+            this.byPeer.delete(conn.peer.toString());
+    }
+}
+/* =========================== In-memory Transport =========================== */
+/**
+ * A transport that keeps everything inside the current process.  Useful for
+ * tests where we want to simulate a cluster without opening TCP sockets.
+ */
+export class InMemoryTransport {
+    self;
+    /** Shared registry so peer transports find each other. */
+    static registry = new Map();
+    handler = () => { };
+    stopped = false;
+    constructor(self) {
+        this.self = self;
+    }
+    setHandler(handler) { this.handler = handler; }
+    async start() {
+        InMemoryTransport.registry.set(this.self.toString(), this);
+    }
+    async shutdown() {
+        this.stopped = true;
+        InMemoryTransport.registry.delete(this.self.toString());
+    }
+    send(to, msg) {
+        if (this.stopped)
+            return;
+        const peer = InMemoryTransport.registry.get(to.toString());
+        if (!peer || peer.stopped)
+            return;
+        const from = this.self;
+        // Decouple sender and receiver via microtask so ordering mirrors TCP.
+        queueMicrotask(() => {
+            if (!peer.stopped)
+                peer.handler(from, msg);
+        });
+    }
+    disconnect(_peer) { }
+    peers() {
+        return Array.from(InMemoryTransport.registry.keys())
+            .filter(k => k !== this.self.toString())
+            .map(k => NodeAddress.parse(k));
+    }
+}
+//# sourceMappingURL=Transport.js.map

package/dist/cluster/Transport.js.map

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

package/dist/cluster/downing/DowningProvider.d.ts

@@ -0,0 +1,32 @@
+import type { Member } from '../Member.js';
+import type { NodeAddress } from '../NodeAddress.js';
+export interface ClusterPartitionView {
+    /** All members the local node currently knows about. */
+    readonly allMembers: ReadonlyArray<Member>;
+    /** Subset of `allMembers` this node considers unreachable. */
+    readonly unreachable: ReadonlySet<string>;
+    /** This node's own address. */
+    readonly self: NodeAddress;
+}
+/**
+ * Decision from a downing strategy — the addresses (serialised as strings)
+ * that should be forcibly downed.  An empty set means "do nothing, wait
+ * for more information".
+ */
+export type DowningDecision = ReadonlySet<string>;
+/**
+ * Pluggable split-brain resolver.  Given the current partition view, pick
+ * the set of nodes to mark down.  Strategies differ in how they break ties
+ * (keep the majority, keep the oldest member, require an admin-defined
+ * quorum, …).
+ */
+export interface DowningProvider {
+    /**
+     * Return addresses to forcibly down.  The empty set means "not yet —
+     * wait for stability or more heartbeats".
+     */
+    decide(view: ClusterPartitionView): DowningDecision;
+}
+/** Helper — `address.toString()` used as map keys consistently. */
+export declare function addrKey(member: Member): string;
+//# sourceMappingURL=DowningProvider.d.ts.map

package/dist/cluster/downing/DowningProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DowningProvider.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/DowningProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe,CAAC;CACrD;AAED,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/cluster/downing/DowningProvider.js

@@ -0,0 +1,5 @@
+/** Helper — `address.toString()` used as map keys consistently. */
+export function addrKey(member) {
+    return member.address.toString();
+}
+//# sourceMappingURL=DowningProvider.js.map

package/dist/cluster/downing/DowningProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DowningProvider.js","sourceRoot":"","sources":["../../../src/cluster/downing/DowningProvider.ts"],"names":[],"mappings":"AAiCA,mEAAmE;AACnE,MAAM,UAAU,OAAO,CAAC,MAAc;IACpC,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;AACnC,CAAC"}

package/dist/cluster/downing/KeepMajority.d.ts

@@ -0,0 +1,21 @@
+import { type ClusterPartitionView, type DowningDecision, type DowningProvider } from './DowningProvider.js';
+export interface KeepMajoritySettings {
+    /** If set, only members carrying this role count toward the majority. */
+    readonly role?: string;
+}
+/**
+ * "Keep majority" — if the reachable side has strictly more than half of
+ * the known members, the minority (unreachable) side is downed.  The minority
+ * side, seeing itself in the minority, downs itself.  Ties (exactly 50/50)
+ * stay pending — the operator must intervene or another strategy must take
+ * over.
+ *
+ * With a `role` restriction only role-tagged members are counted; useful
+ * when you run stateful and stateless nodes in the same cluster.
+ */
+export declare class KeepMajority implements DowningProvider {
+    private readonly settings;
+    constructor(settings?: KeepMajoritySettings);
+    decide(view: ClusterPartitionView): DowningDecision;
+}
+//# sourceMappingURL=KeepMajority.d.ts.map

package/dist/cluster/downing/KeepMajority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeepMajority.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/KeepMajority.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,YAAa,YAAW,eAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,GAAE,oBAAyB;IAEhE,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe;CAyBpD"}

package/dist/cluster/downing/KeepMajority.js

@@ -0,0 +1,39 @@
+import { addrKey, } from './DowningProvider.js';
+/**
+ * "Keep majority" — if the reachable side has strictly more than half of
+ * the known members, the minority (unreachable) side is downed.  The minority
+ * side, seeing itself in the minority, downs itself.  Ties (exactly 50/50)
+ * stay pending — the operator must intervene or another strategy must take
+ * over.
+ *
+ * With a `role` restriction only role-tagged members are counted; useful
+ * when you run stateful and stateless nodes in the same cluster.
+ */
+export class KeepMajority {
+    settings;
+    constructor(settings = {}) {
+        this.settings = settings;
+    }
+    decide(view) {
+        const candidates = view.allMembers.filter((m) => (m.status === 'up' || m.status === 'leaving' || m.status === 'unreachable') &&
+            (!this.settings.role || m.hasRole(this.settings.role)));
+        if (candidates.length === 0)
+            return new Set();
+        const reachable = candidates.filter((m) => !view.unreachable.has(addrKey(m)));
+        const unreachable = candidates.filter((m) => view.unreachable.has(addrKey(m)));
+        const n = candidates.length;
+        const needed = Math.floor(n / 2) + 1;
+        if (reachable.length >= needed) {
+            // Majority on our side: down the unreachable partition.
+            return new Set(unreachable.map(addrKey));
+        }
+        if (unreachable.length >= needed) {
+            // We're the minority — down ourselves and every reachable peer on
+            // this side of the split.
+            return new Set(reachable.map(addrKey));
+        }
+        // Exact tie or insufficient info — remain pending.
+        return new Set();
+    }
+}
+//# sourceMappingURL=KeepMajority.js.map

package/dist/cluster/downing/KeepMajority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeepMajority.js","sourceRoot":"","sources":["../../../src/cluster/downing/KeepMajority.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,GAIR,MAAM,sBAAsB,CAAC;AAO9B;;;;;;;;;GASG;AACH,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,WAAiC,EAAE;QAAnC,aAAQ,GAAR,QAAQ,CAA2B;IAAG,CAAC;IAEpE,MAAM,CAAC,IAA0B;QAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9C,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa,CAAC;YAC3E,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CACvD,CAAC;QACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,GAAG,EAAE,CAAC;QAE9C,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9E,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/E,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QAErC,IAAI,SAAS,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;YAC/B,wDAAwD;YACxD,OAAO,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3C,CAAC;QACD,IAAI,WAAW,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;YACjC,kEAAkE;YAClE,0BAA0B;YAC1B,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QACzC,CAAC;QACD,mDAAmD;QACnD,OAAO,IAAI,GAAG,EAAE,CAAC;IACnB,CAAC;CACF"}

package/dist/cluster/downing/KeepOldest.d.ts

@@ -0,0 +1,23 @@
+import { type ClusterPartitionView, type DowningDecision, type DowningProvider } from './DowningProvider.js';
+export interface KeepOldestSettings {
+    /** If set, only members with this role are eligible "oldest". */
+    readonly role?: string;
+    /**
+     * When true, if the oldest member is unreachable the *other* side wins
+     * (this flips the rule for paranoid setups where the oldest might be
+     * the one that failed).  Default: false.
+     */
+    readonly downIfAlone?: boolean;
+}
+/**
+ * "Keep oldest" — whichever partition contains the oldest cluster member
+ * survives; the other side is downed.  "Oldest" is the lowest address when
+ * addresses are compared lexicographically — consistent with the leader
+ * election in this project.
+ */
+export declare class KeepOldest implements DowningProvider {
+    private readonly settings;
+    constructor(settings?: KeepOldestSettings);
+    decide(view: ClusterPartitionView): DowningDecision;
+}
+//# sourceMappingURL=KeepOldest.d.ts.map

package/dist/cluster/downing/KeepOldest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeepOldest.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/KeepOldest.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,eAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,GAAE,kBAAuB;IAE9D,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe;CA4BpD"}

package/dist/cluster/downing/KeepOldest.js

@@ -0,0 +1,37 @@
+import { addrKey, } from './DowningProvider.js';
+/**
+ * "Keep oldest" — whichever partition contains the oldest cluster member
+ * survives; the other side is downed.  "Oldest" is the lowest address when
+ * addresses are compared lexicographically — consistent with the leader
+ * election in this project.
+ */
+export class KeepOldest {
+    settings;
+    constructor(settings = {}) {
+        this.settings = settings;
+    }
+    decide(view) {
+        const candidates = view.allMembers.filter((m) => (m.status === 'up' || m.status === 'leaving' || m.status === 'unreachable') &&
+            (!this.settings.role || m.hasRole(this.settings.role)));
+        if (candidates.length === 0)
+            return new Set();
+        // Oldest = lowest address (sorted by compareTo).
+        const sorted = [...candidates].sort((a, b) => a.address.compareTo(b.address));
+        const oldest = sorted[0];
+        const oldestReachable = !view.unreachable.has(addrKey(oldest));
+        const reachable = candidates.filter((m) => !view.unreachable.has(addrKey(m)));
+        const unreachable = candidates.filter((m) => view.unreachable.has(addrKey(m)));
+        if (oldestReachable) {
+            // Oldest is on our side — down the other side.
+            return new Set(unreachable.map(addrKey));
+        }
+        // Oldest is unreachable.  Default: treat it as if we lose — down ourselves.
+        if (this.settings.downIfAlone) {
+            return new Set(reachable.map(addrKey));
+        }
+        // Without the override, the conservative default is still: keep the
+        // side with the oldest — which is the *other* side, so we down this one.
+        return new Set(reachable.map(addrKey));
+    }
+}
+//# sourceMappingURL=KeepOldest.js.map

package/dist/cluster/downing/KeepOldest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeepOldest.js","sourceRoot":"","sources":["../../../src/cluster/downing/KeepOldest.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,GAIR,MAAM,sBAAsB,CAAC;AAa9B;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IACQ;IAA7B,YAA6B,WAA+B,EAAE;QAAjC,aAAQ,GAAR,QAAQ,CAAyB;IAAG,CAAC;IAElE,MAAM,CAAC,IAA0B;QAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9C,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa,CAAC;YAC3E,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CACvD,CAAC;QACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,GAAG,EAAE,CAAC;QAE9C,iDAAiD;QACjD,MAAM,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9E,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;QAC1B,MAAM,eAAe,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAE/D,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9E,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/E,IAAI,eAAe,EAAE,CAAC;YACpB,+CAA+C;YAC/C,OAAO,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3C,CAAC;QAED,4EAA4E;QAC5E,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;YAC9B,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QACzC,CAAC;QACD,oEAAoE;QACpE,yEAAyE;QACzE,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/cluster/downing/KeepReferee.d.ts

@@ -0,0 +1,23 @@
+import { type ClusterPartitionView, type DowningDecision, type DowningProvider } from './DowningProvider.js';
+export interface KeepRefereeSettings {
+    /**
+     * Fixed "referee" address; whichever partition contains it survives.
+     * Must match the address format returned by `NodeAddress.toString()`.
+     */
+    readonly refereeAddress: string;
+    /** Additional quorum a.k.a. down-all-if-referee-reachable-but-too-few. */
+    readonly downAllIfBelowQuorum?: number;
+}
+/**
+ * "Keep referee" — the partition containing the designated referee node
+ * wins.  If the referee is unreachable, this side downs itself.  Optionally
+ * enforce a minimum-quorum rule even when the referee is reachable: if the
+ * reachable set has fewer than `downAllIfBelowQuorum` members including the
+ * referee, shut everyone down rather than run with a shaky majority.
+ */
+export declare class KeepReferee implements DowningProvider {
+    private readonly settings;
+    constructor(settings: KeepRefereeSettings);
+    decide(view: ClusterPartitionView): DowningDecision;
+}
+//# sourceMappingURL=KeepReferee.d.ts.map

package/dist/cluster/downing/KeepReferee.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeepReferee.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/KeepReferee.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,eAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,mBAAmB;IAI1D,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe;CAqBpD"}

package/dist/cluster/downing/KeepReferee.js

@@ -0,0 +1,35 @@
+import { addrKey, } from './DowningProvider.js';
+/**
+ * "Keep referee" — the partition containing the designated referee node
+ * wins.  If the referee is unreachable, this side downs itself.  Optionally
+ * enforce a minimum-quorum rule even when the referee is reachable: if the
+ * reachable set has fewer than `downAllIfBelowQuorum` members including the
+ * referee, shut everyone down rather than run with a shaky majority.
+ */
+export class KeepReferee {
+    settings;
+    constructor(settings) {
+        this.settings = settings;
+        if (!settings.refereeAddress)
+            throw new Error('KeepReferee: refereeAddress required');
+    }
+    decide(view) {
+        const candidates = view.allMembers.filter((m) => m.status === 'up' || m.status === 'leaving' || m.status === 'unreachable');
+        const referee = candidates.find((m) => addrKey(m) === this.settings.refereeAddress);
+        if (!referee)
+            return new Set(); // unknown referee — wait
+        const refereeReachable = !view.unreachable.has(addrKey(referee));
+        const reachable = candidates.filter((m) => !view.unreachable.has(addrKey(m)));
+        const unreachable = candidates.filter((m) => view.unreachable.has(addrKey(m)));
+        if (refereeReachable) {
+            if (this.settings.downAllIfBelowQuorum && reachable.length < this.settings.downAllIfBelowQuorum) {
+                // Even the referee side doesn't meet the quorum — down everyone.
+                return new Set(reachable.concat(unreachable).map(addrKey));
+            }
+            return new Set(unreachable.map(addrKey));
+        }
+        // Referee is on the other side — we lose.
+        return new Set(reachable.map(addrKey));
+    }
+}
+//# sourceMappingURL=KeepReferee.js.map

package/dist/cluster/downing/KeepReferee.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeepReferee.js","sourceRoot":"","sources":["../../../src/cluster/downing/KeepReferee.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,GAIR,MAAM,sBAAsB,CAAC;AAY9B;;;;;;GAMG;AACH,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,QAA6B;QAA7B,aAAQ,GAAR,QAAQ,CAAqB;QACxD,IAAI,CAAC,QAAQ,CAAC,cAAc;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACxF,CAAC;IAED,MAAM,CAAC,IAA0B;QAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9C,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa,CAC1E,CAAC;QACF,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QACpF,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC,yBAAyB;QACzD,MAAM,gBAAgB,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAEjE,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9E,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/E,IAAI,gBAAgB,EAAE,CAAC;YACrB,IAAI,IAAI,CAAC,QAAQ,CAAC,oBAAoB,IAAI,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,oBAAoB,EAAE,CAAC;gBAChG,iEAAiE;gBACjE,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAC7D,CAAC;YACD,OAAO,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3C,CAAC;QACD,0CAA0C;QAC1C,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/cluster/downing/LeaseMajority.d.ts

@@ -0,0 +1,70 @@
+import type { Lease } from '../../coordination/Lease.js';
+import { type ClusterPartitionView, type DowningDecision, type DowningProvider } from './DowningProvider.js';
+export interface LeaseMajoritySettings {
+    /**
+     * External arbiter — typically a `KubernetesLease` so both sides
+     * of a partition reach the same K8s API and only one acquires.
+     * Each replica owns its own `Lease` instance with a distinct
+     * `owner` (its node address); the underlying lease record is
+     * shared (same `name`).
+     */
+    readonly lease: Lease;
+    /**
+     * Hard ceiling on a single `acquire()` attempt.  After this we
+     * return no decision and let the next failure-detection tick
+     * trigger a fresh attempt.  Default: 5 s.
+     */
+    readonly acquireTimeoutMs?: number;
+    /** If set, only members carrying this role count toward the majority. */
+    readonly role?: string;
+}
+/**
+ * Split-brain resolver that uses an external `Lease` to break ties
+ * when the cluster splits into equal-sized partitions — the case
+ * where membership-only strategies (KeepOldest, KeepReferee,
+ * KeepMajority) cannot make a deterministic call.
+ *
+ * Algorithm per partition observation (one side of the split):
+ *
+ *   1. Run the standard `KeepMajority` math.
+ *      - Reachable side has strict majority → down the unreachable side.
+ *      - Reachable side is the strict minority → down ourselves
+ *        (and every reachable peer on this side).
+ *   2. Equal-size partition (or insufficient info) → start
+ *      `lease.acquire()`.  Return no decision while the acquire is
+ *      pending so the cluster waits.
+ *   3. When acquire resolves:
+ *      - `true` → we are the surviving side.  Down the unreachable side.
+ *      - `false` → some other side won.  Down our own side.
+ *
+ * The `decide()` interface stays sync (the rest of the resolver
+ * pipeline is sync).  Async work happens off-band — this strategy
+ * is **stateful**: the first equal-size observation kicks off the
+ * acquire; subsequent ticks read the cached result.
+ *
+ * **Lease unavailable** (network problem reaching the K8s API):
+ * `acquire()` rejects → strategy stays in pending state and returns
+ * an empty decision.  Better to wait than to risk both sides
+ * surviving.
+ */
+export declare class LeaseMajority implements DowningProvider {
+    private readonly settings;
+    /** Cached decision once acquire has resolved.  Cleared on a fresh
+     *  partition view so a new split triggers a new acquire. */
+    private decision;
+    /** True while an `acquire()` is in flight. */
+    private acquiring;
+    /** Fingerprint of the partition view we last evaluated.  Used to
+     *  detect a *new* split (different unreachable set) so we restart
+     *  the acquire flow. */
+    private lastFingerprint;
+    /** Wall-clock deadline of the in-flight acquire — used to recover
+     *  if `acquire()` hangs longer than the user's budget. */
+    private acquireDeadline;
+    constructor(settings: LeaseMajoritySettings);
+    decide(view: ClusterPartitionView): DowningDecision;
+    private runAcquire;
+    private reset;
+    private fingerprintOf;
+}
+//# sourceMappingURL=LeaseMajority.d.ts.map

package/dist/cluster/downing/LeaseMajority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LeaseMajority.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/LeaseMajority.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,aAAc,YAAW,eAAe;IAiBvC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAhBrC;gEAC4D;IAC5D,OAAO,CAAC,QAAQ,CAAgC;IAEhD,8CAA8C;IAC9C,OAAO,CAAC,SAAS,CAAS;IAE1B;;4BAEwB;IACxB,OAAO,CAAC,eAAe,CAAuB;IAE9C;8DAC0D;IAC1D,OAAO,CAAC,eAAe,CAAK;gBAEC,QAAQ,EAAE,qBAAqB;IAE5D,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe;YAmErC,UAAU;IAiBxB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,aAAa;CAQtB"}