actor-ts 0.9.1 → 0.11.0

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

@@ -0,0 +1,41 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/** Plain options-object shape accepted by {@link KeepReferee}. */
+export interface KeepRefereeOptionsType {
+    /**
+     * 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;
+}
+/**
+ * Fluent builder for {@link KeepRefereeOptionsType}:
+ *
+ *     new KeepReferee(
+ *       KeepRefereeOptions.create().withRefereeAddress('sys@10.0.0.1:2551'),
+ *     );
+ */
+export declare class KeepRefereeOptionsBuilder extends OptionsBuilder<KeepRefereeOptionsType> {
+    /** Start a fresh builder. */
+    static create(): KeepRefereeOptionsBuilder;
+    /** Fixed referee address; the partition containing it survives. */
+    withRefereeAddress(refereeAddress: string): this;
+    /** Down everyone if the referee side has fewer than this many members. */
+    withDownAllIfBelowQuorum(count: number): this;
+}
+/** Validates resolved {@link KeepRefereeOptionsType} settings. */
+export declare class KeepRefereeOptionsValidator extends OptionsValidator<KeepRefereeOptionsType> {
+    constructor();
+    protected rules(s: Partial<KeepRefereeOptionsType>): void;
+}
+/**
+ * Accepted input for the {@link KeepReferee} constructor: the fluent
+ * {@link KeepRefereeOptionsBuilder} OR a plain {@link KeepRefereeOptionsType}
+ * object.
+ */
+export type KeepRefereeOptions = KeepRefereeOptionsBuilder | Partial<KeepRefereeOptionsType>;
+/** Value alias so `KeepRefereeOptions.create()` / `new KeepRefereeOptions()` resolve to the builder. */
+export declare const KeepRefereeOptions: typeof KeepRefereeOptionsBuilder;
+//# sourceMappingURL=KeepRefereeOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"KeepRefereeOptions.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/KeepRefereeOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED;;;;;;GAMG;AACH,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,sBAAsB,CAAC;IACnF,6BAA6B;IAC7B,MAAM,CAAC,MAAM,IAAI,yBAAyB;IAI1C,mEAAmE;IACnE,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAIhD,0EAA0E;IAC1E,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAG9C;AAED,kEAAkE;AAClE,qBAAa,2BAA4B,SAAQ,gBAAgB,CAAC,sBAAsB,CAAC;;IAIvF,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,IAAI;CAK1D;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAC7F,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,kCAA4B,CAAC"}

package/dist/cluster/downing/KeepRefereeOptions.js

@@ -0,0 +1,38 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/**
+ * Fluent builder for {@link KeepRefereeOptionsType}:
+ *
+ *     new KeepReferee(
+ *       KeepRefereeOptions.create().withRefereeAddress('sys@10.0.0.1:2551'),
+ *     );
+ */
+export class KeepRefereeOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder. */
+    static create() {
+        return new KeepRefereeOptionsBuilder();
+    }
+    /** Fixed referee address; the partition containing it survives. */
+    withRefereeAddress(refereeAddress) {
+        return this.set('refereeAddress', refereeAddress);
+    }
+    /** Down everyone if the referee side has fewer than this many members. */
+    withDownAllIfBelowQuorum(count) {
+        return this.set('downAllIfBelowQuorum', count);
+    }
+}
+/** Validates resolved {@link KeepRefereeOptionsType} settings. */
+export class KeepRefereeOptionsValidator extends OptionsValidator {
+    constructor() {
+        super('KeepRefereeOptions');
+    }
+    rules(s) {
+        if (s.refereeAddress === undefined)
+            this.fail('refereeAddress', 'is required');
+        this.nonEmptyString('refereeAddress');
+        this.positiveInt('downAllIfBelowQuorum');
+    }
+}
+/** Value alias so `KeepRefereeOptions.create()` / `new KeepRefereeOptions()` resolve to the builder. */
+export const KeepRefereeOptions = KeepRefereeOptionsBuilder;
+//# sourceMappingURL=KeepRefereeOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"KeepRefereeOptions.js","sourceRoot":"","sources":["../../../src/cluster/downing/KeepRefereeOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAalE;;;;;;GAMG;AACH,MAAM,OAAO,yBAA0B,SAAQ,cAAsC;IACnF,6BAA6B;IAC7B,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,yBAAyB,EAAE,CAAC;IACzC,CAAC;IAED,mEAAmE;IACnE,kBAAkB,CAAC,cAAsB;QACvC,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,cAAc,CAAC,CAAC;IACpD,CAAC;IAED,0EAA0E;IAC1E,wBAAwB,CAAC,KAAa;QACpC,OAAO,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,OAAO,2BAA4B,SAAQ,gBAAwC;IACvF;QACE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC9B,CAAC;IACS,KAAK,CAAC,CAAkC;QAChD,IAAI,CAAC,CAAC,cAAc,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC;QAC/E,IAAI,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC;QACtC,IAAI,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAC3C,CAAC;CACF;AAQD,wGAAwG;AACxG,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAC"}

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

@@ -1,23 +1,5 @@
-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;
-}
+import type { LeaseMajorityOptions } from './LeaseMajorityOptions.js';
 /**
  * Split-brain resolver that uses an external `Lease` to break ties
  * when the cluster splits into equal-sized partitions — the case
@@ -46,9 +28,41 @@ export interface LeaseMajoritySettings {
  * `acquire()` rejects → strategy stays in pending state and returns
  * an empty decision.  Better to wait than to risk both sides
  * surviving.
+ *
+ * **Slow / hung acquire (#142 split-brain hardening)**
+ *
+ * If `lease.acquire()` hasn't resolved by `acquireTimeoutMs`, the
+ * defence-in-depth logic kicks in:
+ *
+ *   - **Epoch invalidation** — every kickoff captures a monotonic
+ *     `acquireEpoch`.  The timeout-recovery bumps the epoch, so a
+ *     late-arriving result from the timed-out attempt is dropped
+ *     (it can't write a stale `decision`).
+ *   - **Release-on-abandon** — we fire-and-forget `lease.release()`
+ *     to undo any acquire that may have succeeded on the wire
+ *     after we gave up locally.  Without this, an acquire that
+ *     timed out on the client but succeeded on the server leaves
+ *     the lease record claimed without anyone observing the win —
+ *     a classic stale-token split-brain vector.
+ *   - **Fail-safe on release failure** — if the abandoning release
+ *     itself rejects, the lease state is now ambiguous (we may or
+ *     may not hold it; we can't tell).  The strategy enters
+ *     fail-safe: every subsequent `decide()` for the same partition
+ *     view returns an empty decision, refusing to claim majority
+ *     until the partition heals (which resets the fail-safe flag).
+ *
+ * **Fencing tokens (optional)**
+ *
+ * If the underlying `Lease` implements `acquireWithToken()` (K8s
+ * Lease's `resourceVersion`, Redis SETNX with counter, etc.), the
+ * strategy uses it instead of plain `acquire()`.  The token isn't
+ * inspected at decide-time — the local epoch is the source of
+ * truth for "is this result still valid?" — but having the token
+ * means tighter integration with the underlying lease's native
+ * fencing primitive (e.g. release-with-token semantics, when
+ * future work adds them).
  */
 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;
@@ -61,9 +75,37 @@ export declare class LeaseMajority implements DowningProvider {
     /** 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);
+    /**
+     * Monotonic counter incremented on every acquire kickoff AND on
+     * every timeout / reset.  `runAcquire` captures the epoch at start
+     * and drops its result if the epoch has moved on by the time it
+     * resolves — that's the core of #142's stale-acquire protection.
+     */
+    private acquireEpoch;
+    /**
+     * Set when an abandoning `release()` itself failed.  The lease's
+     * holder identity is now ambiguous and we MUST NOT claim majority
+     * until the partition heals (which clears the flag).  See #142.
+     */
+    private failSafe;
+    private readonly options;
+    constructor(options: LeaseMajorityOptions);
     decide(view: ClusterPartitionView): DowningDecision;
+    /**
+     * Run a single acquire attempt, scoped to a captured epoch.  The
+     * write to `this.decision` only happens if the epoch is still
+     * current at resolve time — that's how we drop stale results
+     * from a previously-timed-out attempt.
+     */
     private runAcquire;
+    /**
+     * Best-effort release of any in-flight ownership after a timeout.
+     * If the release itself rejects, the lease state is ambiguous and
+     * the strategy enters fail-safe.  Same epoch as the abandoned
+     * acquire — if a fresh acquire has already kicked off (incremented
+     * epoch beyond ours), the failure isn't ours to act on.
+     */
+    private runAbandonRelease;
     private reset;
     private fingerprintOf;
 }

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

@@ -1 +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"}
+{"version":3,"file":"LeaseMajority.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/LeaseMajority.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,oBAAoB,EAA4B,MAAM,2BAA2B,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,qBAAa,aAAc,YAAW,eAAe;IACnD;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;IAE5B;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAAK;IAEzB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;gBAEvC,OAAO,EAAE,oBAAoB;IAKzC,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe;IAsFnD;;;;;OAKG;YACW,UAAU;IA4CxB;;;;;;OAMG;YACW,iBAAiB;IAe/B,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,aAAa;CAQtB"}

package/dist/cluster/downing/LeaseMajority.js

@@ -1,4 +1,5 @@
 import { addrKey, } from './DowningProvider.js';
+import { LeaseMajorityOptionsValidator } from './LeaseMajorityOptions.js';
 /**
  * Split-brain resolver that uses an external `Lease` to break ties
  * when the cluster splits into equal-sized partitions — the case
@@ -27,9 +28,41 @@ import { addrKey, } from './DowningProvider.js';
  * `acquire()` rejects → strategy stays in pending state and returns
  * an empty decision.  Better to wait than to risk both sides
  * surviving.
+ *
+ * **Slow / hung acquire (#142 split-brain hardening)**
+ *
+ * If `lease.acquire()` hasn't resolved by `acquireTimeoutMs`, the
+ * defence-in-depth logic kicks in:
+ *
+ *   - **Epoch invalidation** — every kickoff captures a monotonic
+ *     `acquireEpoch`.  The timeout-recovery bumps the epoch, so a
+ *     late-arriving result from the timed-out attempt is dropped
+ *     (it can't write a stale `decision`).
+ *   - **Release-on-abandon** — we fire-and-forget `lease.release()`
+ *     to undo any acquire that may have succeeded on the wire
+ *     after we gave up locally.  Without this, an acquire that
+ *     timed out on the client but succeeded on the server leaves
+ *     the lease record claimed without anyone observing the win —
+ *     a classic stale-token split-brain vector.
+ *   - **Fail-safe on release failure** — if the abandoning release
+ *     itself rejects, the lease state is now ambiguous (we may or
+ *     may not hold it; we can't tell).  The strategy enters
+ *     fail-safe: every subsequent `decide()` for the same partition
+ *     view returns an empty decision, refusing to claim majority
+ *     until the partition heals (which resets the fail-safe flag).
+ *
+ * **Fencing tokens (optional)**
+ *
+ * If the underlying `Lease` implements `acquireWithToken()` (K8s
+ * Lease's `resourceVersion`, Redis SETNX with counter, etc.), the
+ * strategy uses it instead of plain `acquire()`.  The token isn't
+ * inspected at decide-time — the local epoch is the source of
+ * truth for "is this result still valid?" — but having the token
+ * means tighter integration with the underlying lease's native
+ * fencing primitive (e.g. release-with-token semantics, when
+ * future work adds them).
  */
 export class LeaseMajority {
-    settings;
     /** Cached decision once acquire has resolved.  Cleared on a fresh
      *  partition view so a new split triggers a new acquire. */
     decision = null;
@@ -42,18 +75,33 @@ export class LeaseMajority {
     /** Wall-clock deadline of the in-flight acquire — used to recover
      *  if `acquire()` hangs longer than the user's budget. */
     acquireDeadline = 0;
-    constructor(settings) {
-        this.settings = settings;
+    /**
+     * Monotonic counter incremented on every acquire kickoff AND on
+     * every timeout / reset.  `runAcquire` captures the epoch at start
+     * and drops its result if the epoch has moved on by the time it
+     * resolves — that's the core of #142's stale-acquire protection.
+     */
+    acquireEpoch = 0;
+    /**
+     * Set when an abandoning `release()` itself failed.  The lease's
+     * holder identity is now ambiguous and we MUST NOT claim majority
+     * until the partition heals (which clears the flag).  See #142.
+     */
+    failSafe = false;
+    options;
+    constructor(options) {
+        this.options = options;
+        new LeaseMajorityOptionsValidator().validate(this.options);
     }
     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)));
+            (!this.options.role || m.hasRole(this.options.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;
+        const count = candidates.length;
+        const needed = Math.floor(count / 2) + 1;
         const fingerprint = this.fingerprintOf(reachable, unreachable);
         // No partition (everyone reachable) → reset state, no decision.
         if (unreachable.length === 0) {
@@ -78,6 +126,15 @@ export class LeaseMajority {
         }
         // Equal-size partition (or stuck-quorum corner case) — Lease
         // arbitration kicks in.
+        // Fail-safe: a prior abandon-release failed and the lease state
+        // is ambiguous.  Refuse to claim majority until the partition
+        // heals (which clears the flag via reset()).  Refuses to even
+        // kick off a fresh acquire — we don't know whether we already
+        // hold the lease, so a fresh acquire might "succeed" trivially
+        // (same-owner renew) and give us a false win.  #142.
+        if (this.failSafe) {
+            return new Set();
+        }
         if (this.decision !== null) {
             // Cached from a prior tick on this same view.
             return this.decision;
@@ -85,45 +142,113 @@ export class LeaseMajority {
         if (this.acquiring) {
             // Recover if the acquire stalled past its budget.  The Lease
             // implementation is supposed to honour its own retry/timeout
-            // settings, but defence-in-depth: if it hasn't resolved by
-            // the deadline, treat it as a transient failure and let the
-            // next tick try again.
+            // options, but defence-in-depth: if it hasn't resolved by
+            // the deadline, bump the epoch (so the late result is dropped)
+            // and proactively release any in-flight ownership — see #142.
             if (Date.now() > this.acquireDeadline) {
                 this.acquiring = false;
+                // Bump the epoch FIRST so the late runAcquire bails out before
+                // it can touch `this.decision`.
+                this.acquireEpoch += 1;
+                // Fire-and-forget release.  If it rejects, the lease state is
+                // ambiguous and we must enter fail-safe — see runAbandonRelease.
+                void this.runAbandonRelease();
             }
             return new Set();
         }
         const surviveSet = new Set(unreachable.map(addrKey));
         const downSelfSet = new Set(reachable.map(addrKey));
         this.acquiring = true;
-        this.acquireDeadline = Date.now() + (this.settings.acquireTimeoutMs ?? 5_000);
-        void this.runAcquire(surviveSet, downSelfSet);
+        this.acquireDeadline = Date.now() + (this.options.acquireTimeoutMs ?? 5_000);
+        this.acquireEpoch += 1;
+        const myEpoch = this.acquireEpoch;
+        void this.runAcquire(myEpoch, surviveSet, downSelfSet);
         return new Set();
     }
     /* ------------------------------ internals ------------------------------ */
-    async runAcquire(surviveSet, downSelfSet) {
+    /**
+     * Run a single acquire attempt, scoped to a captured epoch.  The
+     * write to `this.decision` only happens if the epoch is still
+     * current at resolve time — that's how we drop stale results
+     * from a previously-timed-out attempt.
+     */
+    async runAcquire(myEpoch, surviveSet, downSelfSet) {
         let won;
         try {
-            won = await this.settings.lease.acquire();
+            // Prefer the fencing-token API when the backend implements it.
+            // The token isn't inspected here (local epoch is sufficient for
+            // stale detection at decide-time), but using the API where
+            // available means the underlying lease's native fencing
+            // primitive participates in the round-trip — useful for backend-
+            // specific consistency checks and a stepping-stone for future
+            // release-with-token semantics.
+            if (typeof this.options.lease.acquireWithToken === 'function') {
+                const result = await this.options.lease.acquireWithToken();
+                won = result !== null;
+            }
+            else {
+                won = await this.options.lease.acquire();
+            }
         }
         catch {
             // Lease backend unreachable — stay pending.  The next decide()
             // call sees `acquiring=false` (we clear it below) and restarts.
-            this.acquiring = false;
+            // But only if our epoch is still current; otherwise the timeout
+            // path has already moved on and we should not touch shared state.
+            if (myEpoch === this.acquireEpoch) {
+                this.acquiring = false;
+            }
+            return;
+        }
+        // Stale resolve: the defence-in-depth timeout (or a reset()) has
+        // already invalidated this attempt.  Drop the result silently —
+        // a fresh acquire is either already in flight or will be kicked
+        // off on the next decide().  Critical for #142: without this
+        // guard a slow `acquire() → true` could write `decision=surviveSet`
+        // after the operator considered the attempt abandoned, producing
+        // a split-brain where both sides "win".
+        if (myEpoch !== this.acquireEpoch) {
             return;
         }
         this.acquiring = false;
         this.decision = won ? surviveSet : downSelfSet;
     }
+    /**
+     * Best-effort release of any in-flight ownership after a timeout.
+     * If the release itself rejects, the lease state is ambiguous and
+     * the strategy enters fail-safe.  Same epoch as the abandoned
+     * acquire — if a fresh acquire has already kicked off (incremented
+     * epoch beyond ours), the failure isn't ours to act on.
+     */
+    async runAbandonRelease() {
+        const myEpoch = this.acquireEpoch;
+        try {
+            await this.options.lease.release();
+        }
+        catch {
+            // Release failed.  We may or may not hold the lease — we can't
+            // tell.  Mark fail-safe so we don't claim majority on this
+            // view.  But only if our epoch is still current; if a partition
+            // heal has already reset() us, this older failure is moot.
+            if (myEpoch === this.acquireEpoch) {
+                this.failSafe = true;
+            }
+        }
+    }
     reset() {
         this.decision = null;
         this.acquiring = false;
         this.lastFingerprint = null;
+        this.failSafe = false;
+        // Bump the epoch so any in-flight runAcquire from before the
+        // reset drops its result instead of writing to the cleared
+        // decision.
+        this.acquireEpoch += 1;
     }
     fingerprintOf(reachable, unreachable) {
-        const r = reachable.map((m) => m.address.toString()).sort().join(',');
-        const u = unreachable.map((m) => m.address.toString()).sort().join(',');
-        return `R[${r}]|U[${u}]`;
+        const reachableKey = reachable.map((m) => m.address.toString()).sort().join(',');
+        const unreachableKey = unreachable.map((m) => m.address.toString()).sort().join(',');
+        return `R[${reachableKey}]|U[${unreachableKey}]`;
     }
 }
 //# sourceMappingURL=LeaseMajority.js.map

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

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

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

@@ -0,0 +1,55 @@
+import type { Lease } from '../../coordination/Lease.js';
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/** Plain options-object shape accepted by {@link LeaseMajority}. */
+export interface LeaseMajorityOptionsType {
+    /**
+     * 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;
+}
+/**
+ * Fluent builder for {@link LeaseMajorityOptionsType}:
+ *
+ *     new LeaseMajority(
+ *       LeaseMajorityOptions.create()
+ *         .withLease(kubernetesLease)
+ *         .withAcquireTimeoutMs(5_000),
+ *     );
+ */
+export declare class LeaseMajorityOptionsBuilder extends OptionsBuilder<LeaseMajorityOptionsType> {
+    /** Start a fresh builder. */
+    static create(): LeaseMajorityOptionsBuilder;
+    /** External arbiter lease — both sides of a partition contend for it. */
+    withLease(lease: Lease): this;
+    /** Hard ceiling on a single `acquire()` attempt in ms.  Default 5 s. */
+    withAcquireTimeoutMs(ms: number): this;
+    /** Only members carrying this role count toward the majority. */
+    withRole(role: string): this;
+}
+/** Validates resolved {@link LeaseMajorityOptionsType} settings. */
+export declare class LeaseMajorityOptionsValidator extends OptionsValidator<LeaseMajorityOptionsType> {
+    constructor();
+    protected rules(_s: Partial<LeaseMajorityOptionsType>): void;
+}
+/**
+ * Accepted input for the {@link LeaseMajority} constructor: the fluent
+ * {@link LeaseMajorityOptionsBuilder} OR a plain {@link LeaseMajorityOptionsType}
+ * object.
+ */
+export type LeaseMajorityOptions = LeaseMajorityOptionsBuilder | Partial<LeaseMajorityOptionsType>;
+/** Value alias so `LeaseMajorityOptions.create()` / `new LeaseMajorityOptions()` resolve to the builder. */
+export declare const LeaseMajorityOptions: typeof LeaseMajorityOptionsBuilder;
+//# sourceMappingURL=LeaseMajorityOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LeaseMajorityOptions.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/LeaseMajorityOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,oEAAoE;AACpE,MAAM,WAAW,wBAAwB;IACvC;;;;;;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;;;;;;;;GAQG;AACH,qBAAa,2BAA4B,SAAQ,cAAc,CAAC,wBAAwB,CAAC;IACvF,6BAA6B;IAC7B,MAAM,CAAC,MAAM,IAAI,2BAA2B;IAI5C,yEAAyE;IACzE,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAI7B,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAItC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAG7B;AAED,oEAAoE;AACpE,qBAAa,6BAA8B,SAAQ,gBAAgB,CAAC,wBAAwB,CAAC;;IAI3F,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,wBAAwB,CAAC,GAAG,IAAI;CAG7D;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,2BAA2B,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;AACnG,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB,oCAA8B,CAAC"}

package/dist/cluster/downing/LeaseMajorityOptions.js

@@ -0,0 +1,41 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/**
+ * Fluent builder for {@link LeaseMajorityOptionsType}:
+ *
+ *     new LeaseMajority(
+ *       LeaseMajorityOptions.create()
+ *         .withLease(kubernetesLease)
+ *         .withAcquireTimeoutMs(5_000),
+ *     );
+ */
+export class LeaseMajorityOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder. */
+    static create() {
+        return new LeaseMajorityOptionsBuilder();
+    }
+    /** External arbiter lease — both sides of a partition contend for it. */
+    withLease(lease) {
+        return this.set('lease', lease);
+    }
+    /** Hard ceiling on a single `acquire()` attempt in ms.  Default 5 s. */
+    withAcquireTimeoutMs(ms) {
+        return this.set('acquireTimeoutMs', ms);
+    }
+    /** Only members carrying this role count toward the majority. */
+    withRole(role) {
+        return this.set('role', role);
+    }
+}
+/** Validates resolved {@link LeaseMajorityOptionsType} settings. */
+export class LeaseMajorityOptionsValidator extends OptionsValidator {
+    constructor() {
+        super('LeaseMajorityOptions');
+    }
+    rules(_s) {
+        this.positiveNumber('acquireTimeoutMs');
+    }
+}
+/** Value alias so `LeaseMajorityOptions.create()` / `new LeaseMajorityOptions()` resolve to the builder. */
+export const LeaseMajorityOptions = LeaseMajorityOptionsBuilder;
+//# sourceMappingURL=LeaseMajorityOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LeaseMajorityOptions.js","sourceRoot":"","sources":["../../../src/cluster/downing/LeaseMajorityOptions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAsBlE;;;;;;;;GAQG;AACH,MAAM,OAAO,2BAA4B,SAAQ,cAAwC;IACvF,6BAA6B;IAC7B,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,2BAA2B,EAAE,CAAC;IAC3C,CAAC;IAED,yEAAyE;IACzE,SAAS,CAAC,KAAY;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,wEAAwE;IACxE,oBAAoB,CAAC,EAAU;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,iEAAiE;IACjE,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,OAAO,6BAA8B,SAAQ,gBAA0C;IAC3F;QACE,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAChC,CAAC;IACS,KAAK,CAAC,EAAqC;QACnD,IAAI,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC;IAC1C,CAAC;CACF;AAQD,4GAA4G;AAC5G,MAAM,CAAC,MAAM,oBAAoB,GAAG,2BAA2B,CAAC"}

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

@@ -1,10 +1,5 @@
 import { type ClusterPartitionView, type DowningDecision, type DowningProvider } from './DowningProvider.js';
-export interface StaticQuorumSettings {
-    /** Exact size of the quorum needed on the reachable side. */
-    readonly quorumSize: number;
-    /** If set, only members carrying this role count toward quorum. */
-    readonly role?: string;
-}
+import type { StaticQuorumOptions } from './StaticQuorumOptions.js';
 /**
  * "Static quorum" — as long as at least `quorumSize` reachable members are
  * up on this side, keep them and down the rest.  Otherwise, down ourselves.
@@ -14,8 +9,8 @@ export interface StaticQuorumSettings {
  * shrink below the threshold.
  */
 export declare class StaticQuorum implements DowningProvider {
-    private readonly settings;
-    constructor(settings: StaticQuorumSettings);
+    private readonly options;
+    constructor(options: StaticQuorumOptions);
     decide(view: ClusterPartitionView): DowningDecision;
 }
 //# sourceMappingURL=StaticQuorum.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"StaticQuorum.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/StaticQuorum.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,qBAAa,YAAa,YAAW,eAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,oBAAoB;IAM3D,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe;CAepD"}
+{"version":3,"file":"StaticQuorum.d.ts","sourceRoot":"","sources":["../../../src/cluster/downing/StaticQuorum.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,mBAAmB,EAA2B,MAAM,0BAA0B,CAAC;AAE7F;;;;;;;GAOG;AACH,qBAAa,YAAa,YAAW,eAAe;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAEtC,OAAO,EAAE,mBAAmB;IAKxC,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe;CAepD"}

package/dist/cluster/downing/StaticQuorum.js

@@ -1,4 +1,5 @@
 import { addrKey, } from './DowningProvider.js';
+import { StaticQuorumOptionsValidator } from './StaticQuorumOptions.js';
 /**
  * "Static quorum" — as long as at least `quorumSize` reachable members are
  * up on this side, keep them and down the rest.  Otherwise, down ourselves.
@@ -8,19 +9,17 @@ import { addrKey, } from './DowningProvider.js';
  * shrink below the threshold.
  */
 export class StaticQuorum {
-    settings;
-    constructor(settings) {
-        this.settings = settings;
-        if (settings.quorumSize < 1) {
-            throw new Error('StaticQuorum: quorumSize must be >= 1');
-        }
+    options;
+    constructor(options) {
+        this.options = options;
+        new StaticQuorumOptionsValidator().validate(this.options);
     }
     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)));
+            (!this.options.role || m.hasRole(this.options.role)));
         const reachable = candidates.filter((m) => !view.unreachable.has(addrKey(m)));
         const unreachable = candidates.filter((m) => view.unreachable.has(addrKey(m)));
-        if (reachable.length >= this.settings.quorumSize) {
+        if (reachable.length >= this.options.quorumSize) {
             return new Set(unreachable.map(addrKey));
         }
         // Not enough reachable — we're below quorum, down ourselves.

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

@@ -1 +1 @@
-{"version":3,"file":"StaticQuorum.js","sourceRoot":"","sources":["../../../src/cluster/downing/StaticQuorum.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,GAIR,MAAM,sBAAsB,CAAC;AAS9B;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,QAA8B;QAA9B,aAAQ,GAAR,QAAQ,CAAsB;QACzD,IAAI,QAAQ,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,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;QAEF,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,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;YACjD,OAAO,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3C,CAAC;QACD,6DAA6D;QAC7D,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACzC,CAAC;CACF"}
+{"version":3,"file":"StaticQuorum.js","sourceRoot":"","sources":["../../../src/cluster/downing/StaticQuorum.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,GAIR,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAGxE;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACN,OAAO,CAA0B;IAElD,YAAY,OAA4B;QACtC,IAAI,CAAC,OAAO,GAAG,OAAkC,CAAC;QAClD,IAAI,4BAA4B,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5D,CAAC;IAED,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,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CACrD,CAAC;QAEF,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,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;YAChD,OAAO,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3C,CAAC;QACD,6DAA6D;QAC7D,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACzC,CAAC;CACF"}