rogue_machines 0.1.1-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 642a94554e3fc861c63351c2a3eb7c638660e18e4391126e003242d8b8548737
+  data.tar.gz: 83eee7560dd5c148a2c5d238afa7a9c18f4aa8ceda22b84edd64eedbaa173345
+SHA512:
+  metadata.gz: 7c35ef2d9b24ef523bec6e3418ec3e4e144ff6cdfa20fa43cdf47aeffe1d8711490ecddaca1d50091c076244f14835fd473de9b1f0de68ab3e1df67f408308f3
+  data.tar.gz: 0513c4ad37a65ab265a1508719dfe0fc692f02fb2ba50ad64af9dd7ffdb92a1e49152b6a700aa2082735470d755fd3633e89084e136772f98cce3558871baedd

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.1](https://github.com/seuros/rogue_machines/compare/rogue_machines-v0.1.0...rogue_machines/v0.1.1) (2026-11-01)
+
+
+### Features
+
+* fault injection, disarmed by default, with an expiry it cannot outlive ([e6cfe89](https://github.com/seuros/rogue_machines/commit/e6cfe8999947dbfb048eaf15a13cb2d4dbb03943))
+* pass a rubygems OTP through the environment ([4f60306](https://github.com/seuros/rogue_machines/commit/4f60306bf35aa8fc7336432c0cdd13b61004796b))
+
+
+### Bug Fixes
+
+* collect the built gems whatever depth the download puts them at ([a470d97](https://github.com/seuros/rogue_machines/commit/a470d97586dad75365425ff5fdde68a982863262))
+* the release tag carries the gem name, and the gate uses the aggregate output ([1c980cd](https://github.com/seuros/rogue_machines/commit/1c980cd0a36bdce2913e1a74252f90987183f0f7))

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 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,211 @@
+# RogueMachines 💥
+
+> **Controlled sabotage for the fleet.** The ship that breaks your systems on
+> purpose, so the void doesn't get to do it first.
+
+Every other vessel in this fleet exists to survive a failure. None of them can
+produce one. A breaker that has never opened, a retry budget that has never
+been spent and a deadline that has never been hit are three untested claims
+flying in formation. **AMS Gray** arms the failure that tests them.
+
+---
+
+## 🚀 Launch Sequence
+
+```bash
+# Add to your ship's Gemfile
+gem 'rogue_machines'
+```
+
+Requires **Ruby 4.0+** and a Rust toolchain, or a platform gem.
+
+---
+
+## 🎯 Mission Brief
+
+```ruby
+require 'rogue_machines'
+
+RogueMachines.arm(:payments, fault: :raise, share: 0.01, expires_in: 300)
+
+RogueMachines.run(:payments) do
+  Payments.charge(order)
+end
+```
+
+One call in a hundred now fails for the next five minutes, and the breaker
+wrapped around it finally gets to prove it works.
+
+---
+
+## 🛡️ Safety Interlocks
+
+**Weapons are cold until you arm them.** A process that has armed nothing
+injects nothing, and `run` says so by validating the name and reading one word
+through one native call.
+
+```ruby
+RogueMachines.armed?                                      # => false
+RogueMachines.run(:payments) { Payments.charge(order) }   # the real call
+```
+
+It allocates nothing: zero objects per call for a Symbol, a String or a frozen
+String name. The overhead is about 160 ns, most of it the name check rather
+than the native read. That is why this ships as a runtime dependency rather
+than a test-only one. The interlock sits on every call to every protected
+dependency, so it has to be cheap enough to leave in.
+
+Nothing is armed by loading the gem, by an environment variable or by a config
+file. Arming is an explicit call naming a target and a share of traffic.
+
+---
+
+## ⏱️ Every Experiment Self-Destructs
+
+`expires_in:` is **required**. There is no way to arm an experiment that
+outlives the officer who armed it, and no constructor in the Rust core that
+takes a fault without a reading it expires at.
+
+```ruby
+RogueMachines.arm(:payments, fault: :raise, share: 1.0, expires_in: 60)
+RogueMachines.armed             # => [:payments]
+
+# sixty seconds later, with nobody touching anything
+RogueMachines.armed             # => []
+RogueMachines.armed?            # => false
+```
+
+An expiry is **observed, not scheduled**: nothing retires an experiment until
+something takes a reading. The first `run`, `armed` or `armed?` at or after the
+expiry retires it, and once retired a clock that steps backwards cannot bring
+it back.
+
+An experiment lasts at most twenty-four hours. Past that it is configuration,
+not an experiment, and it must be armed again deliberately.
+
+---
+
+## 💥 The Armory
+
+```ruby
+# Fail.
+RogueMachines.arm(:payments, fault: :raise, share: 0.01, expires_in: 300)
+
+# Be slow, then make the real call.
+RogueMachines.arm(:search, fault: :delay, delay: 2, share: 0.5, expires_in: 300)
+
+# Succeed, with a substitute.
+RogueMachines.arm(:catalogue, fault: :garble, garbled: [], share: 0.1, expires_in: 300)
+```
+
+A `:raise` raises `RogueMachines::Injected`. A `:garble` returns `garbled:`
+without running the block, which defaults to `nil` so a forgotten substitute
+cannot quietly return the real value.
+
+**There is no weapon that holds a caller forever.** A dependency that times out
+is a `:delay` longer than the caller's own budget, which leaves the caller's
+timeout in charge of when it gives up. The delay is spent against the ambient
+`deadline_machines` budget, so a stall inside a deadline trips that deadline
+instead of sleeping past it. Because a deadline is opt-in per call site, a
+delay is also capped at five minutes. That is not a substitute for a deadline;
+it bounds what a mistyped argument can do to a caller that has none.
+
+---
+
+## 🎲 Targeting
+
+`share:` is a fraction of calls between 0 and 1, and the draw deciding each
+call comes from `RogueMachines.random`. Replace it to replay an exact run:
+
+```ruby
+RogueMachines.random = Random.new(1234)
+```
+
+A share is half open at its own boundary and expressed in millionths, so 0.0
+reaches nothing and 1.0 reaches everything. It is a threshold from zero rather
+than an interval: 0.1 and 0.9 both cover a low draw, so two experiments cannot
+divide one stream of calls between them. A share below one millionth is
+refused rather than armed as a silent no-op.
+
+---
+
+## 🕰️ The Ship's Chronometer
+
+`RogueMachines.clock` delegates to `DeadlineMachines.clock`, so a test can
+expire an experiment without sleeping:
+
+```ruby
+RogueMachines.clock = DeadlineMachines::TestClock.new
+RogueMachines.arm(:payments, fault: :raise, share: 1.0, expires_in: 60)
+RogueMachines.clock.advance(60)
+RogueMachines.armed?            # => false
+```
+
+This is the one place `RogueMachines` consumes a primitive from the fleet
+rather than tripping it.
+
+**Install the chronometer through `RogueMachines.clock=`.** Doing so disarms
+everything first, because every armed expiry was computed against the outgoing
+clock and an expiry is only meaningful against the clock it came from.
+
+It is safe to do under load. A reading is taken before any lock, so that a
+caller's clock never runs inside one, which means a call can be part way
+through when the clock is replaced. Each reading therefore carries the
+generation it belongs to, and a call arriving with a superseded one is refused
+rather than acted on: arming raises and nothing is armed, a decision makes the
+real call, and a query reports nothing. A clock being replaced faster than a
+reading can be taken is answered the same way rather than retried forever, and
+a clock returning something that is not a non-negative Integer of nanoseconds
+raises an error naming the clock.
+
+Replacing `DeadlineMachines.clock` underneath is reflected, since the
+delegation is not memoised, but it cannot disarm anything. A clock whose epoch
+is lower than the old one then makes an armed experiment look as though its
+expiry is still far away. Set `RogueMachines.clock` and the question does not
+arise.
+
+A reading is also taken before the lock when arming, so the expiry of a new
+experiment is measured from slightly before it is armed. With a real monotonic
+clock that is microseconds. Nothing infers that a reading came from a
+different clock: with several threads taking their own readings, a reading
+older than the arming is ordinary interleaving, and treating it as evidence of
+a clock change retires experiments that were just armed.
+
+---
+
+## 🔩 The Native Extension Is Required
+
+There is no pure-Ruby fallback and no switch to turn one on. `require
+'rogue_machines'` loads the extension and fails if it is not there. The gem is
+a binding to the `rogue-machines` crate in `ext/rogue_machines_native/core`,
+which has zero dependencies and builds `no_std` for wasm and for a
+microcontroller. The binding asks for its `std` feature, so the crate as this
+gem consumes it is not `no_std`.
+
+---
+
+## 🚫 Rules of Engagement
+
+- **No breaker, limiter, retry or budget.** It trips those. `breaker_machines`,
+  `throttle_machines`, `chrono_machines` and `shed_machines` own them.
+- **No clock of its own.** Every reading is nanoseconds the caller passes in,
+  which is why the core builds for bare metal.
+- **No randomness of its own.** The draw is the caller's.
+- **No capacity beyond 32 experiments**, because the armed set is one 32-bit
+  word and the interlock on the hot path is a single load of it.
+
+---
+
+## 📡 Credits
+
+**AMS Gray**, NCC-0401, *Gray*-class raider.
+
+Named for Jim Gray's *Why Do Computers Stop and What Can Be Done About It?*
+(1985), which argued that the way to find out whether a system tolerates
+faults is to give it some.
+
+---
+
+## License
+
+MIT

data/ext/rogue_machines_native/extconf.rb

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

data/lib/rogue_machines/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RogueMachines
+  VERSION = '0.1.1'
+end

data/lib/rogue_machines.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'deadline_machines'
+
+require_relative 'rogue_machines/version'
+
+# Rogue, Injection, Error and Injected are defined by the native extension;
+# there is no pure-Ruby implementation to fall back to.
+require 'rogue_machines_native/rogue_machines_native'
+
+# Fault injection: making a dependency fail, stall or lie on purpose.
+#
+# Disarmed is the default. `run` costs one native call that reads one word
+# until something is armed.
+module RogueMachines
+  # Attempts at one consistent reading before giving up on a clock that is
+  # being replaced faster than it can be read.
+  READINGS = 100
+
+  @registry = Rogue.new
+  @substitutes = {}.freeze
+  @lock = Mutex.new
+
+  class << self
+    attr_writer :random
+
+    # Monotonic nanoseconds. Delegates to deadline_machines rather than
+    # memoising it, so replacing that gem's clock moves every expiry with it.
+    def clock
+      @clock || DeadlineMachines.clock
+    end
+
+    # Installing a clock disarms everything first. Every armed expiry was
+    # computed against the outgoing clock, and an expiry measured against a
+    # clock it did not come from is not an expiry.
+    #
+    # It also starts a generation, so a reading already taken against the
+    # outgoing clock is refused rather than compared against expiries it has
+    # no relation to. `sweep` is destructive, so such a reading would retire
+    # experiments armed after the swap.
+    def clock=(clock)
+      @lock.synchronize do
+        # The native call goes last here, against the rule the other two-store
+        # writes follow, because this order is observable: `reading` is
+        # lock-free, and bumping the generation first would pair an outgoing
+        # reading with the incoming generation, which every consumer accepts.
+        Thread.handle_interrupt(Object => :never) do
+          @substitutes = {}.freeze
+          @clock = clock
+          registry.invalidate
+        end
+      end
+    end
+
+    def random
+      @random ||= Random.new
+    end
+
+    def registry
+      @registry
+    end
+
+    # Arms an experiment under `name`, replacing any already there.
+    #
+    #   RogueMachines.arm(:payments, fault: :raise, share: 0.01, expires_in: 300)
+    #   RogueMachines.arm(:slow, fault: :delay, delay: 2, share: 1.0, expires_in: 60)
+    #   RogueMachines.arm(:lies, fault: :garble, garbled: [], share: 0.5, expires_in: 60)
+    #
+    # `expires_in` is required and counts from now, so no experiment outlives
+    # the person who armed it.
+    def arm(name, fault:, share:, expires_in:, delay: nil, garbled: nil)
+      key = named(name)
+
+      # The reading is taken before the lock so that a caller's clock never
+      # runs inside it, which means the expiry is measured from slightly
+      # before the arming. See "The clock is deadline_machines'" in the README.
+      pair = reading
+      unless pair
+        raise Error, "the clock was replaced #{READINGS} times while taking one reading; " \
+                     'nothing is armed'
+      end
+
+      now, age = pair
+      options = { fault: fault.to_s, share: Float(share), expires_in: Float(expires_in),
+                  now_ns: now, generation: age }
+      options[:delay] = Float(delay) if delay
+
+      @lock.synchronize do
+        # Two stores. An interrupt landing between them would leave an armed
+        # garble with nothing to return for the rest of its life, and nothing
+        # repairs that, because publishing only ever removes keys.
+        Thread.handle_interrupt(Object => :never) do
+          registry.arm(key, **options)
+          payload = options[:fault] == 'garble' ? garbled : nil
+          publish(substitutes.merge(key => payload), registry.armed(now, age))
+        end
+      end
+      name
+    end
+
+    # Reports whether `name` was still running, which an experiment that
+    # expired on its own is not.
+    #
+    # The substitute goes first: a call landing between the two sees a garble
+    # with nothing to return rather than the real value it was armed against.
+    def disarm(name)
+      key = named(name)
+      pair = reading
+      return false unless pair
+
+      now, age = pair
+      @lock.synchronize do
+        # A reading from a replaced clock must not drop a substitute belonging
+        # to the generation that replaced it.
+        break false unless registry.generation == age
+
+        # The native call validates its reading and can raise, so it goes
+        # first: nothing is mutated unless it succeeds. Ordering no longer
+        # matters to a reader, since a decision and its payload are read
+        # under this same lock.
+        Thread.handle_interrupt(Object => :never) do
+          was_running = registry.disarm(key, now, age)
+          @substitutes = substitutes.except(key).freeze
+          was_running
+        end
+      end
+    end
+
+    def disarm_all
+      @lock.synchronize do
+        Thread.handle_interrupt(Object => :never) do
+          registry.disarm_all
+          @substitutes = {}.freeze
+        end
+      end
+    end
+
+    # With no name, whether anything at all is armed. Asked through the name
+    # list rather than the gate `run` reads, because the gate only drops an
+    # expired experiment when something next decides.
+    def armed?(name = nil)
+      names = running
+      return names.any? if name.nil?
+
+      names.include?(named(name))
+    end
+
+    # The experiments still running, which excludes any that has expired.
+    def armed
+      running.map(&:to_sym)
+    end
+
+    # Runs the block, or the fault armed under `name` instead.
+    def run(name)
+      check(name)
+      unless registry.any_armed?
+        release unless substitutes.empty?
+        return yield
+      end
+
+      key = named(name)
+      pair = reading
+      return yield unless pair
+
+      now, age = pair
+      drawn = random.rand(PER_MILLION)
+
+      # The decision and the payload live in different stores, so reading them
+      # one after the other is wrong in both orders: a name published between
+      # the two is in the decision and not the table, and one retired between
+      # them is in the table and not the decision. They are read together.
+      # Nothing caller-supplied runs inside the lock, since the clock and the
+      # draw are already taken.
+      injection, payload = @lock.synchronize do
+        found = registry.decide(key, now, drawn, age)
+        [found, found && substitutes[key]]
+      end
+      reconcile(now, age)
+      return yield unless injection
+
+      case injection.fault
+      when :raise then raise Injected, "#{name} is armed to raise"
+      when :garble then payload
+      when :delay
+        stall(injection.delay_ns)
+        yield
+      end
+    end
+
+    private
+
+    def substitutes
+      @substitutes
+    end
+
+    # A reading and the generation it belongs to.
+    #
+    # The generation is read on both sides of the reading. Reading it only
+    # afterwards would adopt the new one and hand a stale reading to a
+    # destructive sweep; reading it only before would pair an outgoing
+    # reading with the incoming generation, which every consumer accepts. The
+    # pair cannot be sampled in one step, so a change means retry.
+    def reading
+      READINGS.times do
+        age = registry.generation
+        now = clock.now_ns
+        unless now.is_a?(Integer) && !now.negative?
+          raise Error, "#{clock.class} returned #{now.inspect}; a reading must be a " \
+                       'non-negative Integer of nanoseconds'
+        end
+        return [now, age] if registry.generation == age
+      end
+      nil
+    end
+
+    # Rejects a name the native table could not key on, without converting it,
+    # so a call site answers the same way whether or not anything is armed.
+    def check(name)
+      case name
+      when Symbol then legible(name.name)
+      when String then legible(name)
+      else raise ArgumentError, "an experiment name must be a Symbol or a String, got #{name.class}"
+      end
+    end
+
+    def legible(name)
+      raise ArgumentError, 'an experiment needs a name' if name.empty?
+      return if name.ascii_only?
+      return if name.encoding == Encoding::UTF_8 && name.valid_encoding?
+      raise ArgumentError, "an experiment name must be valid UTF-8, got #{name.encoding}" \
+        unless name.encoding == Encoding::UTF_8
+
+      raise ArgumentError, 'an experiment name holds bytes that are not valid UTF-8'
+    end
+
+    # The checked name, as something the native table can key on. Not `to_s`:
+    # a String subclass can override it, which armed one name and reported
+    # another.
+    def named(name)
+      check(name)
+      name.is_a?(Symbol) ? name.name : name
+    end
+
+    # The names still running, releasing the substitutes of everything that is
+    # not.
+    def running
+      pair = reading
+      return [] unless pair
+
+      now, age = pair
+      @lock.synchronize do
+        # A reading from a replaced clock lists nothing, and must not be used
+        # to prune: publishing against an empty list would wipe the table.
+        break [] unless registry.generation == age
+
+        names = registry.armed(now, age)
+        publish(substitutes, names)
+        names
+      end
+    end
+
+    # Releases the substitutes of anything no longer running, so one armed
+    # experiment holding the gate open cannot keep another's substitute, and
+    # the caller's object, alive until the next `arm`.
+    def reconcile(now_ns, age)
+      return if substitutes.size <= registry.armed_count(now_ns, age)
+
+      @lock.synchronize do
+        publish(substitutes, registry.armed(now_ns, age)) if registry.generation == age
+      end
+    end
+
+    # Only if nothing is armed once the lock is held. The gate `run` reads is
+    # sampled before it, so an `arm` landing in between would otherwise have
+    # its just-published substitute discarded, leaving an armed garble with
+    # nothing to return for the rest of its life.
+    def release
+      @lock.synchronize { @substitutes = {}.freeze unless registry.any_armed? }
+    end
+
+    # Replaces the table with the entries `names` still covers, in one
+    # assignment.
+    def publish(table, names)
+      @substitutes = table.slice(*names).freeze
+    end
+
+    # Spends the delay against the caller's deadline rather than past it, so a
+    # slow dependency trips the timeout that was already there.
+    def stall(delay_ns)
+      DeadlineMachines.check!
+      seconds = DeadlineMachines.clamp_sleep(delay_ns.fdiv(NS_PER_SECOND))
+      sleep(seconds) if seconds.positive?
+      DeadlineMachines.check!
+    end
+  end
+end

data/sig/rogue_machines.rbs

@@ -0,0 +1,146 @@
+# Fault injection: making a dependency fail, stall or lie on purpose.
+module RogueMachines
+  VERSION: String
+
+  # Nanoseconds in a second.
+  NS_PER_SECOND: Integer
+
+  # Millionths in a whole, the unit a share is held in.
+  PER_MILLION: Integer
+
+  # Experiments a process can arm at once, the width of the armed mask.
+  EXPERIMENTS: Integer
+
+  # Attempts at one consistent reading before giving up on a clock being
+  # replaced faster than it can be read.
+  READINGS: Integer
+
+  class Error < StandardError
+  end
+
+  # Raised by a `:raise` fault in place of the real call.
+  class Injected < Error
+  end
+
+  # The fault to perform for one call.
+  class Injection < ::Data
+    # `:raise`, `:delay` or `:garble`.
+    attr_reader fault: Symbol
+
+    # How long a `:delay` waits, and zero for the others.
+    attr_reader delay_ns: Integer
+  end
+
+  # Anything that reports monotonic nanoseconds.
+  interface _Clock
+    def now_ns: () -> Integer
+  end
+
+  # Anything that draws below a bound, which `Random` satisfies.
+  interface _Random
+    def rand: (Integer bound) -> Integer
+  end
+
+  # The experiments a process is running, by name. Reach it through the module.
+  class Rogue
+    def self.new: () -> instance
+
+    # Whether any experiment is armed as of the last sweep, which is the whole
+    # of the decision a disarmed process takes. A sweep happens on every
+    # `decide` and every `armed`, so this trails an expiry by one call.
+    def any_armed?: () -> bool
+
+    # Sweeps expired experiments at `now_ns`, then counts what is left.
+    # Reports 0 without sweeping for a superseded generation. Every seam
+    # taking a reading refuses a Float rather than truncating it.
+    def armed_count: (Integer now_ns, Integer generation) -> Integer
+
+    # Arms `name`, replacing any experiment already there. Raises
+    # `ArgumentError` for an unknown fault, a share outside a whole or below
+    # one millionth, a duration that is non-positive, below a nanosecond or
+    # longer than the cap, a `now_ns` that is not an Integer or is outside the
+    # range, or a `:delay`
+    # with no `delay:`. Raises `Error` when every slot is taken. Nothing is
+    # armed and no slot is taken when it raises.
+    def arm: (String name, fault: String, share: Float, expires_in: Float,
+              now_ns: Integer, generation: Integer, ?delay: Float) -> void
+
+    # Reports whether `name` was still running, which an experiment that
+    # expired on its own is not.
+    def disarm: (String name, Integer now_ns, Integer generation) -> bool
+
+    def disarm_all: () -> void
+
+    # Which clock the armed expiries were computed against. Every reading is
+    # only meaningful for one of these, and a call carrying another one is
+    # refused rather than acted on, since sweeping is destructive.
+    def generation: () -> Integer
+
+    # Disarms everything and starts a generation, retiring readings already
+    # taken against the outgoing clock. Returns the new generation.
+    def invalidate: () -> Integer
+
+    # The names still running at `now_ns`, in no particular order, and none
+    # for a superseded generation.
+    def armed: (Integer now_ns, Integer generation) -> Array[String]
+
+    # The fault to perform, or `nil` to make the real call. Raises
+    # `ArgumentError` for a `draw` or `now_ns` that is not an Integer, is
+    # outside its range, or is a `draw` at or above `PER_MILLION`. A Float is
+    # refused rather than truncated, because a truncated draw becomes 0,
+    # which every share covers.
+    def decide: (String name, Integer now_ns, Integer draw, Integer generation) -> Injection?
+
+    def inspect: () -> String
+  end
+
+  # Delegates to `DeadlineMachines.clock` when unset, rather than memoising
+  # it, so replacing that clock moves every expiry with it.
+  def self.clock: () -> _Clock
+
+  # Disarms everything first: an armed expiry was computed against the
+  # outgoing clock and is not meaningful against another one.
+  def self.clock=: (_Clock?) -> void
+  def self.random: () -> _Random
+  def self.random=: (_Random?) -> void
+    # The registry itself. Reach for the module methods instead: arming
+    # through this bypasses the substitute a `:garble` returns, and freezing
+    # it does not prevent arming, since the native side holds its own state.
+  def self.registry: () -> Rogue
+
+  # Arms an experiment under `name`. `expires_in` counts from now and is
+  # required, so no experiment outlives the person who armed it.
+  #
+  # Raises `ArgumentError` for a blank name, a name that is neither ASCII nor
+  # valid UTF-8, or any argument the registry refuses. Raises `Error` when
+  # every slot is taken, when the clock was replaced faster than a reading
+  # could be taken, and when the clock returned something that is not a
+  # non-negative Integer of nanoseconds.
+  #
+  # `share`, `expires_in` and `delay` go through `Float()`, so a String that
+  # parses as a number is accepted, one that does not raises `ArgumentError`,
+  # and a value with no numeric conversion at all raises `TypeError`.
+  def self.arm: (Symbol | String name, fault: Symbol | String, share: Numeric | String,
+                 expires_in: Numeric | String, ?delay: (Numeric | String)?,
+                 ?garbled: untyped) -> (Symbol | String)
+
+  def self.disarm: (Symbol | String name) -> bool
+  def self.disarm_all: () -> void
+
+  # With no name, whether anything at all is armed.
+  def self.armed?: (?(Symbol | String)?) -> bool
+
+  # The experiments still running, which excludes any that has expired.
+  def self.armed: () -> Array[Symbol]
+
+  # Runs the block, or the fault armed under `name` instead. Not the block's
+  # own type: a `:garble` returns the substitute it was armed with, which is
+  # whatever the caller passed as `garbled:`. Makes the real call when the
+  # clock was replaced faster than a reading could be taken.
+  #
+  # Raises `Injected` for a `:raise` fault, which is the point of the gem,
+  # `DeadlineMachines::Error` when a `:delay` spends the ambient budget,
+  # `ArgumentError` for a name it cannot key on or a draw the random gave it,
+  # and `Error` for a clock returning an unusable reading.
+  def self.run: (Symbol | String name) { () -> untyped } -> untyped
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: rogue_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: arm64-darwin
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: deadline_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: 'Fault injection for chaos engineering: arms a named experiment that
+  makes a dependency fail, stall or lie for a share of calls, so the breakers, retries
+  and budgets around it can be shown to work. Bound to Ruby from the zero-dependency
+  rogue-machines crate. Disarmed by default, and every experiment carries an expiry
+  it cannot outlive.'
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/rogue_machines_native/extconf.rb
+- lib/rogue_machines.rb
+- lib/rogue_machines/version.rb
+- lib/rogue_machines_native/rogue_machines_native.bundle
+- sig/rogue_machines.rbs
+homepage: https://github.com/seuros/rogue_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/rogue_machines
+  changelog_uri: https://github.com/seuros/rogue_machines/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/seuros/rogue_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: rogue_machines_native
+  cargo_manifest_path: ext/rogue_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: Fault injection and chaos engineering for Ruby
+test_files: []