election_machines 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 280d87432c4bb945291b1a804fb690e94886adef86720e4cb7bc78a4b8967808
+  data.tar.gz: 413925e9d82a374a269bc9f5718d354a507a0775bf65f96ce8d0662961bd2eb9
+SHA512:
+  metadata.gz: e8fff2087448de2e665d69c0dc28409c658764b26f9c3f23e134635b61c37e26a5047607bd90d4218c65585a00ecdad714ec03a38b443f06fc8099232d840db8
+  data.tar.gz: 69a3fcdbf2d8870101053a4aad8a4fbed843251b53aa0e7a41b1c08862b695c2b6f535d5309d5dbd74e2660d2bd66ada395f4004ae6252c3ac6ef978878b1b1a

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.1.5](https://github.com/seuros/election_machines/compare/election_machines/v0.1.4...election_machines/v0.1.5) (2026-11-06)
+
+
+### Bug Fixes
+
+* extract Wrapper::advance for election revision handling ([09bdd65](https://github.com/seuros/election_machines/commit/09bdd65226a7780bfe980bf19e5145ee2c2f1da0))
+
+## [0.1.4](https://github.com/seuros/election_machines/compare/election_machines/v0.1.3...election_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* require lease-machines 0.3 ([d99d292](https://github.com/seuros/election_machines/commit/d99d2928ba0dd42e3013eb2d13e9a527387703ee))
+
+## [0.1.3](https://github.com/seuros/election_machines/compare/election_machines/v0.1.2...election_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([8c6d66c](https://github.com/seuros/election_machines/commit/8c6d66cc9ff19907ad68dc4043c9e421a66037ad))
+
+## [0.1.2](https://github.com/seuros/election_machines/compare/election_machines/v0.1.1...election_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([27f00f1](https://github.com/seuros/election_machines/commit/27f00f1331d641a7d324ee7e560324a99f958bfa))
+
+## [0.1.1](https://github.com/seuros/election_machines/compare/election_machines-v0.1.0...election_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([a804dd3](https://github.com/seuros/election_machines/commit/a804dd3a3c37b0f96acec918e7242475a63cd0c4))

data/Cargo.toml

@@ -0,0 +1,23 @@
+[workspace]
+members = ["ext/election_machines_native/core", "ext/election_machines_native/ffi"]
+default-members = ["ext/election_machines_native/core"]
+resolver = "3"
+[workspace.package]
+edition = "2024"
+rust-version = "1.99"
+license = "MIT"
+[workspace.dependencies]
+election-machines = { path = "ext/election_machines_native/core" }
+magnus = { version = "0.9.3", default-features = false }
+rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api-compiled-fallback"] }
+lease-machines = ">=0.3"
+[workspace.lints.rust]
+unsafe_code = "deny"
+unused_must_use = "warn"
+missing_docs = "warn"
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+unwrap_used = "deny"
+expect_used = "deny"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# ElectionMachines
+
+> One captain at a time, and silence from the bridge is not a vacancy. 📡
+
+Leader election for Ruby, backed by a lease. You hand in the list of workers that showed up, it names one of them captain and gives them a lease with a token. The captain keeps the chair by heartbeating before the lease runs out. Everyone else is told who the incumbent is. Nobody gets the chair by shouting louder, and a captain who stops answering loses it only when the clock says so.
+
+## Quick Start
+
+```bash
+gem 'election_machines'
+```
+
+```ruby
+election = ElectionMachines::Election.new
+
+# Three workers report in. The lowest id takes the chair.
+status, leader, token, expires_at = election.elect([9, 2, 5], clock.now, 30.0)
+# => ["elected", 2, 1, 30.0]
+
+# The leader keeps the chair by heartbeating with its token.
+election.heartbeat(2, token, clock.now, 30.0)
+# => ["renewed", 2, 1, ...]
+
+# Anyone else asking while the lease is live just learns who's in charge.
+election.elect([5], clock.now, 30.0)
+# => ["incumbent", 2, 1, ...]
+```
+
+Every call returns the same four-element shape: a status string, then the leader, token, and expiry, or three nils when there's nothing to report.
+
+## A Message to the Resistance
+
+So you have three schedulers and only one of them should be ticking the cron table. You picked "lowest hostname wins" and it worked for a year. Then the lowest hostname hit a network partition for ninety seconds. The other two couldn't reach it, decided it was dead, and the second-lowest took over. The first one never knew. For ninety seconds you had two captains, and your billing job ran twice.
+
+"It stopped answering" and "it's gone" are different facts. The first is what you observed. The second is what you assumed. The gap between them is where the double-charge lives.
+
+An election built on a lease closes that gap. The leader holds the chair until a stated time, not until someone stops hearing from it. If it's quiet but the lease is live, the answer to "can I take over?" is still no. When the lease lapses, the next election hands out a new token, and the old captain's token stops working everywhere it's checked.
+
+## Chapter 1: Stardate 2025.186, the AMS LeLann
+
+> **AMS LeLann**, NCC-4206, *LeLann*-class command relay.
+> An unanswered hail is not permission to appoint a second captain.
+
+The relay doesn't fly the ship. It keeps the roster and the chair. When a crew reports for duty, the relay names the lowest-numbered one captain and stamps a lease. Captains renew by hailing with their token. A crew that hails about an empty chair gets it. A crew that hails about an occupied one is told who sits there, and nothing else.
+
+Somewhere on a lower deck, a lieutenant proposes:
+
+```ruby
+def am_i_leader?
+  peers.none? { |peer| peer.alive? && peer.id < my_id }
+end
+```
+
+"That," says the relay officer, "is how a ship ends up with two captains during a comms blackout."
+
+## The Flight Plan
+
+```mermaid
+stateDiagram-v2
+    [*] --> vacant
+    vacant --> held: elect, lowest candidate wins, token n
+    held --> held: heartbeat by leader with token, renewed
+    held --> held: elect by anyone before expiry, incumbent
+    held --> vacant: resign by leader with token, released
+    held --> held: lease lapses, next elect names a new leader with token n+1
+```
+
+And the ninety seconds the cron leader went quiet:
+
+```mermaid
+sequenceDiagram
+    participant A as Scheduler A (id 1)
+    participant E as Election
+    participant B as Scheduler B (id 2)
+
+    A->>E: elect([1, 2], t=0, ttl=30)
+    E-->>A: elected, leader 1, token 1, expires 30
+    Note over A: ticks the cron table, heartbeats every 10s
+    A->>E: heartbeat(1, token 1, t=10, ttl=30)
+    E-->>A: renewed, expires 40
+
+    Note over A: partitioned at t=12, silent
+
+    B->>E: elect([2], t=20, ttl=30)
+    E-->>B: incumbent, leader 1, token 1, expires 40
+    Note over B: lease still live. B waits.
+
+    B->>E: elect([2], t=45, ttl=30)
+    E-->>B: elected, leader 2, token 2, expires 75
+    Note over B: now ticks the cron table
+
+    Note over A: partition heals at t=50
+    A->>E: heartbeat(1, token 1, t=50, ttl=30)
+    E-->>A: WrongOwner
+    Note over A: stands down. One captain the whole time.
+```
+
+## How the Relay Works
+
+### Elect
+
+Pass the ids of the workers that are present, the current time, and how long the lease should last. The lowest id wins. The token starts at 1 and only ever goes up.
+
+```ruby
+election = ElectionMachines::Election.new
+
+election.elect([9, 2, 5], 0, 10)   # => ["elected", 2, 1, 10.0]
+election.lease                     # => [2, 1, 10.0]
+```
+
+Ask again while that lease is live and you get the incumbent, even if you offer a lower id. Sitting captains aren't unseated by a late arrival.
+
+```ruby
+election.elect([1], 1, 10)         # => ["incumbent", 2, 1, 10.0]
+```
+
+An empty roster is `no_candidates`.
+
+### Heartbeat
+
+The leader renews by presenting its id and token. The new expiry is counted from `now`.
+
+```ruby
+election = ElectionMachines::Election.new
+election.elect([2], 0, 10)
+
+election.heartbeat(2, 1, 3, 10)    # => ["renewed", 2, 1, 13.0]
+election.heartbeat(1, 1, 4, 10)    # => ["WrongOwner", nil, nil, nil]
+```
+
+A heartbeat from anyone but the leader is refused and changes nothing.
+
+### Resign
+
+A leader steps down by presenting its token. The chair is vacant immediately, and the next election fills it.
+
+```ruby
+election.resign(2, 1, 5)           # => ["released", nil, nil, nil]
+election.lease                     # => nil
+election.elect([7, 3], 6, 10)      # => ["elected", 3, 2, 16.0]
+```
+
+Token 2. The old token is dead from here on.
+
+### When the leader goes quiet
+
+Nothing happens at the moment of expiry. The chair is only re-filled when someone asks. Until then, `lease` still describes the lapsed lease, so you can see who was last in charge.
+
+```ruby
+election = ElectionMachines::Election.new
+election.elect([2], 0, 10)
+
+election.heartbeat(2, 1, 11, 10)   # => ["Expired", nil, nil, nil]
+election.lease                     # => [2, 1, 10.0]
+
+election.elect([5], 12, 10)        # => ["elected", 5, 2, 22.0]
+election.heartbeat(2, 1, 13, 10)   # => ["WrongOwner", nil, nil, nil]
+```
+
+The old leader's late heartbeat is rejected with `WrongOwner`. Its token is also stale, and `StaleToken` is what you'd see if it had the right id and the wrong token.
+
+### Time only moves forward
+
+You supply `now`. The election remembers the latest it has seen and refuses to go backwards.
+
+```ruby
+election = ElectionMachines::Election.new
+election.elect([2], 5, 10)
+election.elect([2], 0, 10)         # => ["ClockRegressed", nil, nil, nil]
+```
+
+Feed it a monotonic clock. Not the wall clock.
+
+## Checkpoints
+
+An election can hand you a `Checkpoint` and roll back to it, but only itself, and only to the most recent one.
+
+```ruby
+election = ElectionMachines::Election.new
+election.elect([1], 0, 10)
+saved = election.checkpoint
+
+election.heartbeat(1, 1, 1, 10)    # => ["renewed", 1, 1, 11.0]
+election.restore!(saved)           # => ArgumentError, a transition happened since
+```
+
+Any successful transition, or any successful restore, invalidates every checkpoint taken before it. That rules out rewinding past a decision someone has already acted on. A checkpoint from one election can't be fed to another. This is for testing and in-process simulation, not for surviving a restart.
+
+## The Rules of the Relay
+
+- **Ids and tokens are Integers** in `0..2**64-1`. Up to 64 candidates per election. Floats and strings raise `TypeError`, out of range raises `RangeError`, a 65th candidate raises `ArgumentError`.
+- **Times are seconds** as Integer or Float, from a monotonic origin you choose. `ttl` must be positive. Negative, infinite, NaN, or absurdly large values raise `ArgumentError`.
+- **Rejections don't raise.** `WrongOwner`, `StaleToken`, `Expired`, `ClockRegressed`, and `no_candidates` all come back as a status with three nils. Only malformed input raises.
+- **Bad input never half-applies.** Arguments are checked before anything changes.
+- **Frozen means frozen.** `freeze` the election and `elect`, `heartbeat`, `resign`, and `restore!` raise `FrozenError`. `lease` still reads.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "If I can't reach the leader, the leader is down."
+### Reality: You can't reach the leader. That's all you know.
+
+A partition looks identical to a crash from the outside. If your election promotes on silence, every network hiccup is a coup. If it promotes on lease expiry, the worst case is a leaderless gap of one ttl, which is boring, and boring is what you want from the thing that decides who runs billing.
+
+## What's Yours
+
+The election decides. It doesn't talk to the network, run timers, or store anything across a restart. Run it in one place, write its decisions down before anyone acts on them, and make the thing the leader controls check the token before every action. A token the resource has already seen beaten is a captain who has already been replaced.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: Scheduler A was never dead. It just couldn't hear you say it was.**

data/ext/election_machines_native/core/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.2.2](https://github.com/seuros/election_machines/compare/election-machines-v0.2.1...election-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([8c6d66c](https://github.com/seuros/election_machines/commit/8c6d66cc9ff19907ad68dc4043c9e421a66037ad))
+
+## [0.2.1](https://github.com/seuros/election_machines/compare/election-machines-v0.2.0...election-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([27f00f1](https://github.com/seuros/election_machines/commit/27f00f1331d641a7d324ee7e560324a99f958bfa))
+
+## [0.2.0](https://github.com/seuros/election_machines/compare/election-machines-v0.1.0...election-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([a804dd3](https://github.com/seuros/election_machines/commit/a804dd3a3c37b0f96acec918e7242475a63cd0c4))

data/ext/election_machines_native/core/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "election-machines"
+version = "0.2.2"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Lease-backed deterministic owner nomination"
+readme = "README.md"
+exclude = ["src/**/tests.rs", "tests/"]
+keywords = ["leader-election", "lease", "fencing", "no-std"]
+categories = ["no-std", "algorithms"]
+[dependencies]
+lease-machines.workspace = true
+[lints]
+workspace = true

data/ext/election_machines_native/core/README.md

@@ -0,0 +1,17 @@
+# election-machines
+
+> **AMS LeLann**, NCC-4206, *LeLann*-class command relay.
+
+Engine-room flight manual: model command handovers through one lease authority.
+
+`no_std` lease-backed owner nomination under one authoritative history.
+Among participating candidates, the smallest numeric ID is nominated. An
+unexpired incumbent remains leader even if absent from the current nomination
+list; this list is not a consensus membership configuration.
+
+All lease-machine persistence, fencing, authentication, and clock requirements
+apply. A fresh election instance is a fresh namespace, not failover recovery.
+Empty candidate lists make no authority transition. Heartbeats renew a lease;
+they are not an asynchronous failure detector. This policy is **not Raft,
+quorum voting, or partition-safe leader election without an external serialized
+durable authority**. Raft elections remain in `consensus-machines`.

data/ext/election_machines_native/core/src/lib.rs

@@ -0,0 +1,86 @@
+#![no_std]
+#![doc = include_str!("../README.md")]
+use core::time::Duration;
+use lease_machines::{
+    Checkpoint, Decision, FencingToken, Lease, LeaseAuthority, OwnerId, Rejection,
+};
+
+/// Outcome of nomination under one lease authority.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum Leadership {
+    /// A new leadership token was issued.
+    Elected(Lease),
+    /// The incumbent's unexpired lease remains authoritative.
+    Incumbent(Lease),
+    /// No candidates were supplied; no authority transition occurred.
+    NoCandidates,
+    /// The authority rejected the request.
+    Rejected(Rejection),
+}
+
+/// Deterministic nomination plus a single resource's lease authority.
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct Election {
+    authority: LeaseAuthority,
+}
+
+impl Election {
+    /// Restore the newest committed authority under the same clock origin.
+    #[must_use]
+    pub const fn restore(checkpoint: Checkpoint) -> Self {
+        Self {
+            authority: LeaseAuthority::restore(checkpoint),
+        }
+    }
+
+    /// Nominate the smallest participating identity, respecting a live incumbent.
+    #[must_use]
+    pub fn elect(&mut self, candidates: &[OwnerId], now: Duration, ttl: Duration) -> Leadership {
+        if now < self.authority.checkpoint().observed() {
+            return Leadership::Rejected(Rejection::ClockRegressed);
+        }
+        let Some(candidate) = candidates.iter().copied().min_by_key(|id| id.value()) else {
+            return Leadership::NoCandidates;
+        };
+        match self.authority.acquire(candidate, now, ttl) {
+            Decision::Granted(lease) => Leadership::Elected(lease),
+            Decision::Rejected(Rejection::Occupied) => {
+                // Occupied is returned only with a live incumbent.
+                self.authority.checkpoint().lease().map_or(
+                    Leadership::Rejected(Rejection::NoLease),
+                    Leadership::Incumbent,
+                )
+            }
+            Decision::Rejected(reason) => Leadership::Rejected(reason),
+            _ => Leadership::Rejected(Rejection::NoLease),
+        }
+    }
+
+    /// Renew leadership only for the matching owner and live fencing token.
+    #[must_use]
+    pub fn heartbeat(
+        &mut self,
+        owner: OwnerId,
+        token: FencingToken,
+        now: Duration,
+        ttl: Duration,
+    ) -> Decision {
+        self.authority.renew(owner, token, now, ttl)
+    }
+
+    /// Relinquish leadership while retaining its fencing high-water mark.
+    #[must_use]
+    pub fn resign(&mut self, owner: OwnerId, token: FencingToken, now: Duration) -> Decision {
+        self.authority.release(owner, token, now)
+    }
+
+    /// Capture state for the runtime's durable commit.
+    #[must_use]
+    pub const fn checkpoint(&self) -> Checkpoint {
+        self.authority.checkpoint()
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/election_machines_native/extconf.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+require_relative 'ffi/extconf'

data/ext/election_machines_native/ffi/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "election_machines_native"
+version = "0.1.3"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+test = false
+doctest = false
+
+[dependencies]
+election-machines.workspace = true
+lease-machines.workspace = true
+magnus.workspace = true
+rb-sys.workspace = true
+
+[lints]
+workspace = true

data/ext/election_machines_native/ffi/extconf.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+require 'mkmf'
+require 'pathname'
+require 'rb_sys/mkmf'
+create_rust_makefile('election_machines_native/election_machines_native') do |extension|
+  extension.ext_dir = Pathname(__dir__).relative_path_from(Pathname(Dir.pwd)).to_s
+  extension.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
+end
+makefile = File.join(Dir.pwd, 'Makefile')
+File.write(makefile, File.read(makefile).gsub(
+  /^RB_SYS_CARGO_MANIFEST_DIR \?=.*$/,
+  "RB_SYS_CARGO_MANIFEST_DIR ?= #{File.expand_path(__dir__)}"
+))

data/ext/election_machines_native/ffi/src/init.rs

@@ -0,0 +1,18 @@
+//! Private initialization boundary.
+use magnus::{Error, Ruby, function, method, prelude::*};
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("ElectionMachines")?;
+    module
+        .define_class("Checkpoint", ruby.class_object())?
+        .undef_default_alloc_func();
+    let class = module.define_class("Election", ruby.class_object())?;
+    class.undef_default_alloc_func();
+    class.define_singleton_method("new", function!(crate::Wrapper::new, 0))?;
+    class.define_method("elect", method!(crate::Wrapper::elect, 3))?;
+    class.define_method("heartbeat", method!(crate::Wrapper::heartbeat, 4))?;
+    class.define_method("resign", method!(crate::Wrapper::resign, 3))?;
+    class.define_method("checkpoint", method!(crate::Wrapper::checkpoint, 0))?;
+    class.define_method("restore!", method!(crate::Wrapper::restore, 1))?;
+    class.define_method("lease", method!(crate::Wrapper::lease, 0))
+}

data/ext/election_machines_native/ffi/src/lib.rs

@@ -0,0 +1,154 @@
+//! Thin Ruby translation for lease-backed nomination.
+mod init;
+mod values;
+use election_machines::{Election, Leadership};
+use lease_machines::{Checkpoint, Decision, FencingToken, Lease, OwnerId};
+use magnus::{Error, RArray, Ruby, prelude::*, typed_data::Obj};
+use std::{cell::RefCell, sync::Arc};
+use values::{Id, Seconds};
+
+type Outcome = (String, Option<u64>, Option<u64>, Option<f64>);
+
+#[magnus::wrap(class = "ElectionMachines::Checkpoint", free_immediately, size)]
+struct Saved {
+    owner: Arc<()>,
+    revision: u64,
+    checkpoint: Checkpoint,
+}
+#[magnus::wrap(class = "ElectionMachines::Election", free_immediately, size)]
+struct Wrapper {
+    owner: Arc<()>,
+    state: RefCell<(Election, u64)>,
+}
+
+fn lease_outcome(status: &str, lease: Lease) -> Outcome {
+    (
+        status.into(),
+        Some(lease.owner().value()),
+        Some(lease.token().value()),
+        Some(lease.expires_at().as_secs_f64()),
+    )
+}
+fn decision(result: Decision) -> Outcome {
+    match result {
+        Decision::Granted(lease) => lease_outcome("granted", lease),
+        Decision::Renewed(lease) => lease_outcome("renewed", lease),
+        Decision::Released => ("released".into(), None, None, None),
+        Decision::Rejected(reason) => (format!("{reason:?}"), None, None, None),
+        _ => ("unknown".into(), None, None, None),
+    }
+}
+impl Wrapper {
+    fn new() -> Self {
+        Self {
+            owner: Arc::new(()),
+            state: RefCell::new((Election::default(), 0)),
+        }
+    }
+    fn next_revision(&self, ruby: &Ruby) -> Result<u64, Error> {
+        let revision = self.state.borrow().1.checked_add(1);
+        revision.ok_or_else(|| Error::new(ruby.exception_range_error(), "revision exhausted"))
+    }
+    /// Runs `step` against the election under the next revision, which stales
+    /// every checkpoint taken before it.
+    fn advance<T>(&self, ruby: &Ruby, step: impl FnOnce(&mut Election) -> T) -> Result<T, Error> {
+        let revision = self.next_revision(ruby)?;
+        let mut state = self.state.borrow_mut();
+        state.1 = revision;
+        Ok(step(&mut state.0))
+    }
+    fn elect(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        candidates: RArray,
+        now: Seconds,
+        ttl: Seconds,
+    ) -> Result<Outcome, Error> {
+        rb_self.check_frozen()?;
+        values::interval(ruby, now, ttl)?;
+        let count = candidates.len();
+        if count > 64 {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "at most 64 candidates",
+            ));
+        }
+        let mut owners = [OwnerId::new(0); 64];
+        for (index, owner) in owners[..count].iter_mut().enumerate() {
+            *owner = OwnerId::new(candidates.entry::<Id>(index.cast_signed())?.0);
+        }
+        let result = rb_self.advance(ruby, |election| {
+            election.elect(&owners[..count], now.0, ttl.0)
+        })?;
+        Ok(match result {
+            Leadership::Elected(lease) => lease_outcome("elected", lease),
+            Leadership::Incumbent(lease) => lease_outcome("incumbent", lease),
+            Leadership::NoCandidates => ("no_candidates".into(), None, None, None),
+            Leadership::Rejected(reason) => (format!("{reason:?}"), None, None, None),
+            _ => ("unknown".into(), None, None, None),
+        })
+    }
+    fn heartbeat(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        owner: Id,
+        token: Id,
+        now: Seconds,
+        ttl: Seconds,
+    ) -> Result<Outcome, Error> {
+        rb_self.check_frozen()?;
+        values::interval(ruby, now, ttl)?;
+        let token = values::token(ruby, token)?;
+        let result = rb_self.advance(ruby, |election| {
+            election.heartbeat(OwnerId::new(owner.0), token, now.0, ttl.0)
+        })?;
+        Ok(decision(result))
+    }
+    fn resign(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        owner: Id,
+        token: Id,
+        now: Seconds,
+    ) -> Result<Outcome, Error> {
+        rb_self.check_frozen()?;
+        let token: FencingToken = values::token(ruby, token)?;
+        let result = rb_self.advance(ruby, |election| {
+            election.resign(OwnerId::new(owner.0), token, now.0)
+        })?;
+        Ok(decision(result))
+    }
+    fn checkpoint(&self) -> Saved {
+        let (checkpoint, revision) = {
+            let state = self.state.borrow();
+            (state.0.checkpoint(), state.1)
+        };
+        Saved {
+            owner: Arc::clone(&self.owner),
+            revision,
+            checkpoint,
+        }
+    }
+    fn restore(ruby: &Ruby, rb_self: Obj<Self>, saved: &Saved) -> Result<bool, Error> {
+        rb_self.check_frozen()?;
+        if !Arc::ptr_eq(&rb_self.owner, &saved.owner) || rb_self.state.borrow().1 != saved.revision
+        {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "cross-instance or stale checkpoint",
+            ));
+        }
+        let revision = rb_self.next_revision(ruby)?;
+        *rb_self.state.borrow_mut() = (Election::restore(saved.checkpoint), revision);
+        Ok(true)
+    }
+    fn lease(&self) -> Option<(u64, u64, f64)> {
+        self.state.borrow().0.checkpoint().lease().map(|lease| {
+            (
+                lease.owner().value(),
+                lease.token().value(),
+                lease.expires_at().as_secs_f64(),
+            )
+        })
+    }
+}

data/ext/election_machines_native/ffi/src/values.rs

@@ -0,0 +1,51 @@
+//! Strict Ruby boundary validation.
+use lease_machines::FencingToken;
+use magnus::{Error, Float, Integer, Ruby, TryConvert, Value};
+use std::time::Duration;
+#[derive(Clone, Copy)]
+pub struct Id(pub u64);
+impl TryConvert for Id {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        if Integer::from_value(value).is_none() {
+            return Err(Error::new(
+                Ruby::get_with(value).exception_type_error(),
+                "expected an Integer",
+            ));
+        }
+        u64::try_convert(value).map(Self)
+    }
+}
+#[derive(Clone, Copy)]
+pub struct Seconds(pub Duration);
+impl TryConvert for Seconds {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        let ruby = Ruby::get_with(value);
+        if Integer::from_value(value).is_none() && Float::from_value(value).is_none() {
+            return Err(Error::new(
+                ruby.exception_type_error(),
+                "seconds must be Integer or Float",
+            ));
+        }
+        Duration::try_from_secs_f64(f64::try_convert(value)?)
+            .map(Self)
+            .map_err(|_| {
+                Error::new(
+                    ruby.exception_arg_error(),
+                    "seconds must be finite, nonnegative and representable",
+                )
+            })
+    }
+}
+pub fn token(ruby: &Ruby, value: Id) -> Result<FencingToken, Error> {
+    FencingToken::new(value.0)
+        .ok_or_else(|| Error::new(ruby.exception_arg_error(), "token must be positive"))
+}
+pub fn interval(ruby: &Ruby, now: Seconds, ttl: Seconds) -> Result<(), Error> {
+    if ttl.0.is_zero() || now.0.checked_add(ttl.0).is_none() {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "TTL must be positive and expiration representable",
+        ));
+    }
+    Ok(())
+}

data/lib/election_machines/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module ElectionMachines
+  VERSION = '0.1.5'
+end

data/lib/election_machines.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+require_relative 'election_machines/version'
+require 'election_machines_native/election_machines_native'

data/sig/election_machines.rbs

@@ -0,0 +1,15 @@
+module ElectionMachines
+  VERSION: String
+  type outcome = [String, Integer?, Integer?, Float?]
+  class Checkpoint
+  end
+  class Election
+    def self.new: () -> Election
+    def elect: (Array[Integer], Integer | Float, Integer | Float) -> outcome
+    def heartbeat: (Integer, Integer, Integer | Float, Integer | Float) -> outcome
+    def resign: (Integer, Integer, Integer | Float) -> outcome
+    def checkpoint: () -> Checkpoint
+    def restore!: (Checkpoint) -> bool
+    def lease: () -> [Integer, Integer, Float]?
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: election_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+description: A thin Rust bridge for deterministic nomination and lease renewal. No
+  distributed election service.
+email:
+- oss@seuros.com
+executables: []
+extensions:
+- ext/election_machines_native/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- ext/election_machines_native/core/CHANGELOG.md
+- ext/election_machines_native/core/Cargo.toml
+- ext/election_machines_native/core/README.md
+- ext/election_machines_native/core/src/lib.rs
+- ext/election_machines_native/extconf.rb
+- ext/election_machines_native/ffi/Cargo.toml
+- ext/election_machines_native/ffi/extconf.rb
+- ext/election_machines_native/ffi/src/init.rs
+- ext/election_machines_native/ffi/src/lib.rs
+- ext/election_machines_native/ffi/src/values.rs
+- lib/election_machines.rb
+- lib/election_machines/version.rb
+- sig/election_machines.rbs
+homepage: https://github.com/seuros/election_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/election_machines
+  bug_tracker_uri: https://github.com/seuros/election_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: election_machines_native
+  cargo_manifest_path: ext/election_machines_native/ffi/Cargo.toml
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Native bounded lease-backed nomination model for Ruby
+test_files: []