election_machines 0.1.5-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b961de842cf411204a93a7d9d9355daae92d28dd22de0c337b91229284522fc9
+  data.tar.gz: c2c10df934e7aee20731bcf4ee38e43128ce1c2541030afc1ab78f715a864cbc
+SHA512:
+  metadata.gz: e96dbd0847073ab57f016f0f1ab080a6bdf16dbfbc4efffcb6dcf7288c7dbf2f63285a0fa7b350313314f8cf4a23e3514edcd6708fe939ecc4a4c1d44c9d0da0
+  data.tar.gz: aa0cd946ac97c3ea2ec4920f53eb18dc669683f8c67c62aedc4fecf44f9ab6bdcf346b5e43f6276d133be6bf3cb71b7055321dd256865d9566cd6df17ab054cf

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/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/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/extconf.rb

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

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,62 @@
+--- !ruby/object:Gem::Specification
+name: election_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: arm64-darwin
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: A thin Rust bridge for deterministic nomination and lease renewal. No
+  distributed election service.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/election_machines_native/core/CHANGELOG.md
+- ext/election_machines_native/core/README.md
+- ext/election_machines_native/extconf.rb
+- lib/election_machines.rb
+- lib/election_machines/version.rb
+- lib/election_machines_native/election_machines_native.bundle
+- 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
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Native bounded lease-backed nomination model for Ruby
+test_files: []