behavior_machines 0.1.0-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a37a3004f0df9f28400a7f8685b3a18ad247b5adb4958483f851c69c8e5d636c
+  data.tar.gz: 68aef4f586a4e4c92c98d563964460a9f81ae27479c8feb464bf2a4fc29491a0
+SHA512:
+  metadata.gz: bd33ceefa35b451f89cd67284348a7b110a00d93602a9e8b46a1c715454aa6445f75d7e3a618c983f5ea7a3301f68e19d6b17064332e9a8d2983359e648ad2ca
+  data.tar.gz: a17b122167f2839e7a7d0c502406cfaff81e2ca305ad4dd5d9b26cf1acc13fb9ebf01fa5ad75e4077297aaa59427476dd3bba4f6d63440fdf0e995894214d5c9

data/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Abdelkader Boudih
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,126 @@
+# behavior_machines
+
+Behavior trees with explicit halt semantics for Ruby, following the
+behavior-tree pattern. Pure Ruby, with an optional native backend built on the
+[behavior-machines](ext/behavior_machines_native/core) Rust crate.
+
+Each tick advances as far as the leaves allow. Every running leaf the tree
+abandons, because a parallel decided, a reactive guard flipped, a timeout
+expired, or the tree was halted, gets `halt` called exactly once, in the same
+call. Leaves can therefore own real resources and release them reliably.
+
+Requires Ruby 4.0 or newer.
+
+```ruby
+require 'behavior_machines'
+
+BM = BehaviorMachines
+
+class BatteryLow
+  def tick(robot, _now) = robot.battery < 20 ? :success : :failure
+end
+
+class Charge
+  def tick(robot, _now)
+    return :success if robot.battery == 100
+
+    robot.charging = true
+    :running
+  end
+
+  def halt(robot) = robot.charging = false
+end
+
+class Patrol
+  def tick(_robot, _now) = :running
+end
+
+tree = BM::Tree.new(
+  BM.fallback(
+    BM.sequence(BM.leaf(BatteryLow.new), BM.leaf(Charge.new)),
+    BM.leaf(Patrol.new)
+  )
+)
+
+tree.tick(robot)  # => :running, charging
+tree.halt(robot)  # Charge#halt runs exactly once
+```
+
+## Nodes
+
+- **Leaves**: any object responding to `tick(ctx, now)`, returning
+  `:success`, `:failure`, or `:running`, and optionally `halt(ctx)`. Built-in:
+  `BM.sleep(seconds)`, `BM.always_success`, `BM.always_failure`.
+- **Control**: `BM.sequence`, `BM.reactive_sequence`, `BM.fallback`,
+  `BM.reactive_fallback`, `BM.parallel(*children, success: :all, failure: 1)`,
+  `BM.if_then_else(condition, then_branch, otherwise = nil)`,
+  `BM.while_do_else(condition, body, otherwise = nil)`.
+- **Decorators**, on any node: `inverter`, `force_success`, `force_failure`,
+  `timeout(seconds)`, `repeat(limit)`, `retry_until_successful(limit)`,
+  `keep_running_until_failure`. Limits are an Integer or `:unlimited`; looping
+  decorators finish at most one child run per tick.
+
+Node definitions are immutable `Data` values; `BM::Tree.new` validates and
+compiles them.
+
+## Time
+
+Durations are seconds. The clock is an Integer count of nanoseconds, passed as
+`now:` and defaulting to `BehaviorMachines.now` (monotonic).
+`tree.next_deadline` returns when a running `sleep` or `timeout` next needs a
+tick, so a host can sleep until then.
+
+## Errors
+
+If a leaf or observer raises during a tick, no more leaf code runs in that
+tick: active leaves stay active and idle ones don't start. Every leaf still
+active is then halted, without observer reports, and the first error
+propagates. The raising leaf counts as finished. During a halt, every active
+leaf is halted even if a leaf's `halt` or the observer raises, and the first
+error propagates afterwards.
+
+A leaf returning anything but the three statuses raises
+`BehaviorMachines::InvalidStatusError`. A leaf calling back into the tree
+that is ticking it raises `BehaviorMachines::ReentrantCallError`. Non-local
+exits from a leaf, such as `throw` or `break`, are not supported.
+
+Both backends follow these rules identically; the test suite compares them
+side by side, including with raising leaves.
+
+## Observers
+
+`tree.tick(ctx, observer:)` reports `ticked(node_id, status)` and
+`halted(node_id)` for every node, children before parents. Node ids number the
+definition in pre-order.
+
+## state_machines
+
+`BehaviorMachines::Machine` has leaves for objects powered by the
+[state_machines](https://github.com/state-machines/state_machines) gem:
+
+```ruby
+job_leaves = BM.sequence(
+  BM.leaf(BM::Machine::Fire.new(:job, :start)),
+  BM.leaf(BM::Machine::WaitFor.new(:job, success: :completed, failure: :failed, on_halt: :cancel))
+)
+```
+
+`InState` checks the state, `Fire` fires an event, and `WaitFor` waits for a
+machine something else drives, firing `on_halt` if the tree abandons it.
+
+## Native backend
+
+The native backend runs the same trees on the Rust engine. It is opt-in:
+
+```console
+$ bundle exec rake compile
+$ BEHAVIOR_MACHINES_NATIVE=1 ruby app.rb
+```
+
+`BM::Tree.new(root, backend: :ruby | :native | :auto)` picks one explicitly.
+Leaves stay Ruby, so the gain is limited to the tree walk itself. The test
+suite runs against both backends (`bundle exec rake test:both`).
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).

data/lib/behavior_machines/definition.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module BehaviorMachines
+  # Validates a node definition and lowers it to the plain nested-Array spec
+  # that both backends build from, so they always agree on shape and on the
+  # pre-order numbering observers see.
+  module Definition
+    # The clock is an unsigned 64-bit count of nanoseconds.
+    MAX_NANOS = (2**64) - 1
+
+    module_function
+
+    def compile(node)
+      case node
+      when Node::Leaf then leaf(node.leaf)
+      when Node::AlwaysSuccess then %i[constant success]
+      when Node::AlwaysFailure then %i[constant failure]
+      when Node::Sleep then [:sleep, nanos(node.seconds, 'Sleep')]
+      when Node::Sequence then ordered(node.children, 'Sequence', :success, false)
+      when Node::ReactiveSequence then ordered(node.children, 'ReactiveSequence', :success, true)
+      when Node::Fallback then ordered(node.children, 'Fallback', :failure, false)
+      when Node::ReactiveFallback then ordered(node.children, 'ReactiveFallback', :failure, true)
+      when Node::Parallel then parallel(node)
+      when Node::IfThenElse then conditional(node.condition, node.then_branch, node.otherwise, false)
+      when Node::WhileDoElse then conditional(node.condition, node.body, node.otherwise, true)
+      when Node::Inverter then [:map, compile(node.child), :inverter]
+      when Node::ForceSuccess then [:map, compile(node.child), :force_success]
+      when Node::ForceFailure then [:map, compile(node.child), :force_failure]
+      when Node::Timeout then [:timeout, nanos(node.seconds, 'Timeout'), compile(node.child)]
+      when Node::Repeat then [:loop, compile(node.child), :success, limit(node.limit, 'Repeat')]
+      when Node::RetryUntilSuccessful
+        [:loop, compile(node.child), :failure, limit(node.limit, 'RetryUntilSuccessful')]
+      when Node::KeepRunningUntilFailure then [:loop, compile(node.child), :success, nil]
+      else raise BuildError, "#{node.inspect} is not a BehaviorMachines node"
+      end
+    end
+
+    def leaf(object)
+      raise BuildError, "leaf #{object.inspect} must respond to tick(ctx, now)" unless object.respond_to?(:tick)
+
+      [:leaf, object, object.respond_to?(:halt)]
+    end
+
+    def ordered(children, name, advance_on, reactive)
+      [:ordered, children_of(children, name), advance_on, reactive]
+    end
+
+    def parallel(node)
+      children = children_of(node.children, 'Parallel')
+      [:parallel, children, threshold(node.success, children.size), threshold(node.failure, children.size)]
+    end
+
+    def conditional(condition, branch, otherwise, reactive)
+      # Only nil means absent; anything else must be a node.
+      [:conditional, compile(condition), compile(branch), otherwise.nil? ? nil : compile(otherwise), reactive]
+    end
+
+    def children_of(children, name)
+      raise BuildError, "#{name} needs at least one child" if children.empty?
+
+      children.map { |child| compile(child) }
+    end
+
+    def threshold(value, children)
+      return children if value == :all
+      raise BuildError, "Parallel threshold must be :all or an Integer, got #{value.inspect}" unless value.is_a?(Integer)
+      raise BuildError, "Parallel threshold #{value} must be between 1 and #{children}" unless value.between?(1, children)
+
+      value
+    end
+
+    def nanos(seconds, name)
+      unless seconds.is_a?(Numeric) && seconds.real? && seconds.finite? && !seconds.negative?
+        raise BuildError, "#{name} needs a finite, non-negative number of seconds, got #{seconds.inspect}"
+      end
+
+      nanos = (seconds.to_r * 1_000_000_000).round
+      raise BuildError, "#{name} of #{seconds} seconds exceeds the 64-bit nanosecond clock" if nanos > MAX_NANOS
+
+      nanos
+    end
+
+    def limit(value, name)
+      return nil if value == :unlimited
+      return value if value.is_a?(Integer) && value.between?(0, MAX_NANOS)
+
+      raise BuildError, "#{name} limit must be :unlimited or an Integer in 0..2**64-1, got #{value.inspect}"
+    end
+  end
+end

data/lib/behavior_machines/engine.rb

@@ -0,0 +1,482 @@
+# frozen_string_literal: true
+
+module BehaviorMachines
+  # The pure-Ruby backend. It mirrors the Rust engine node for node; the same
+  # test suite runs against both backends.
+  module Engine
+    MAX_TIME = Definition::MAX_NANOS
+
+    # Discards observer reports.
+    module NullObserver
+      def self.ticked(_id, _status) = nil
+      def self.halted(_id) = nil
+    end
+
+    # One tick or halt. `errors` collects what leaves and observers raise; once
+    # it holds one, no more leaf ticks or observer reports run this call.
+    Run = Data.define(:ctx, :observer, :errors) do
+      def self.start(ctx, observer) = new(ctx, observer || NullObserver, [])
+
+      def failed? = !errors.empty?
+
+      def record(error)
+        errors << error
+        nil
+      end
+
+      def report_ticked(id, status) = report { observer.ticked(id, status) }
+      def report_halted(id) = report { observer.halted(id) }
+
+      private
+
+      def report
+        return if failed?
+
+        yield
+      rescue Exception => e # rubocop:disable Lint/RescueException -- recorded, raised after cleanup
+        record(e)
+      end
+    end
+
+    # A deadline past the end of the clock never fires.
+    def self.deadline_after(now, nanos)
+      deadline = now + nanos
+      deadline > MAX_TIME ? nil : deadline
+    end
+
+    def self.reached?(deadline, now) = !deadline.nil? && now >= deadline
+
+    # Compiled tree plus its execution state.
+    class Tree
+      def initialize(spec)
+        @root = Builder.new.build(spec)
+      end
+
+      # Once a leaf or observer raises, the rest of the tick runs no Ruby: an
+      # active leaf stays active and an idle one does not start. Then every
+      # leaf still active is halted, without observer reports, and the first
+      # error propagates. Errors raised during that cleanup are dropped.
+      def tick(ctx, now, observer)
+        run = Run.start(ctx, observer)
+        status = @root.tick(run, now)
+        return status unless run.failed?
+
+        @root.halt(Run.start(ctx, nil))
+        raise run.errors.first
+      end
+
+      # Every active leaf is halted even if one, or the observer, raises; the
+      # first error propagates afterwards.
+      def halt(ctx, observer)
+        run = Run.start(ctx, observer)
+        @root.halt(run)
+        raise run.errors.first if run.failed?
+      end
+
+      def running? = @root.running?
+      def next_deadline = @root.next_deadline
+    end
+
+    # Builds slots from a spec, numbering nodes in pre-order.
+    class Builder
+      def initialize
+        @next_id = 0
+      end
+
+      def build(spec)
+        id = @next_id
+        @next_id += 1
+        kind, *args = spec
+        case kind
+        when :leaf then LeafSlot.new(id, *args)
+        when :constant then ConstantSlot.new(id, *args)
+        when :sleep then SleepSlot.new(id, *args)
+        when :ordered then ordered(id, *args)
+        when :parallel then parallel(id, *args)
+        when :conditional then conditional(id, *args)
+        when :map then MapSlot.new(id, build(args[0]), args[1])
+        when :timeout then TimeoutSlot.new(id, args[0], build(args[1]))
+        when :loop then LoopSlot.new(id, build(args[0]), args[1], args[2])
+        else raise ArgumentError, "unknown spec #{kind.inspect}"
+        end
+      end
+
+      private
+
+      def ordered(id, children, advance_on, reactive)
+        (reactive ? ReactiveSlot : OrderedSlot).new(id, children.map { |child| build(child) }, advance_on)
+      end
+
+      def parallel(id, children, success, failure)
+        ParallelSlot.new(id, children.map { |child| build(child) }, success, failure)
+      end
+
+      def conditional(id, condition, branch, otherwise, reactive)
+        condition = build(condition)
+        branch = build(branch)
+        otherwise &&= build(otherwise)
+        (reactive ? WhileDoElseSlot : IfThenElseSlot).new(id, condition, branch, otherwise)
+      end
+    end
+
+    # One compiled node. `@running` is set while its last tick returned
+    # :running and it has not been halted since; only running slots halt.
+    class Slot
+      def initialize(id)
+        @id = id
+        @running = false
+      end
+
+      def running? = @running
+
+      def tick(run, now)
+        status = step(run, now, !@running)
+        @running = status == :running
+        run.report_ticked(@id, status)
+        status
+      end
+
+      def halt(run)
+        return unless @running
+
+        @running = false
+        stop(run)
+        run.report_halted(@id)
+      end
+
+      def next_deadline = @running ? running_deadline : nil
+
+      private
+
+      def stop(_run) = nil
+      def running_deadline = nil
+      def halt_all(slots, run) = slots.each { |slot| slot.halt(run) }
+      def earliest(deadlines) = deadlines.compact.min
+    end
+
+    # A user leaf.
+    class LeafSlot < Slot
+      def initialize(id, leaf, halts)
+        super(id)
+        @leaf = leaf
+        @halts = halts
+      end
+
+      private
+
+      # After an error no more leaf code runs this call: an active leaf stays
+      # active (so cleanup halts it) and an idle one does not start. A leaf
+      # that raises counts as finished.
+      def step(run, now, starting)
+        return starting ? :failure : :running if run.failed?
+
+        BehaviorMachines.check_status(@leaf.tick(run.ctx, now), @leaf)
+      rescue Exception => e # rubocop:disable Lint/RescueException -- recorded, raised after cleanup
+        run.record(e)
+        :failure
+      end
+
+      def stop(run)
+        @leaf.halt(run.ctx) if @halts
+      rescue Exception => e # rubocop:disable Lint/RescueException -- recorded; the halt continues
+        run.record(e)
+      end
+    end
+
+    # AlwaysSuccess and AlwaysFailure.
+    class ConstantSlot < Slot
+      def initialize(id, status)
+        super(id)
+        @status = status
+      end
+
+      private
+
+      def step(_run, _now, _starting) = @status
+    end
+
+    class SleepSlot < Slot
+      def initialize(id, nanos)
+        super(id)
+        @nanos = nanos
+        @deadline = nil
+      end
+
+      private
+
+      def step(_run, now, starting)
+        @deadline = Engine.deadline_after(now, @nanos) if starting
+        Engine.reached?(@deadline, now) ? :success : :running
+      end
+
+      def running_deadline = @deadline
+    end
+
+    # Sequence and Fallback with memory: resume the running child.
+    class OrderedSlot < Slot
+      def initialize(id, children, advance_on)
+        super(id)
+        @children = children
+        @advance_on = advance_on
+        @cursor = 0
+      end
+
+      private
+
+      def step(run, now, _starting)
+        while (child = @children[@cursor])
+          status = child.tick(run, now)
+          return :running if status == :running
+          return finish(status) unless status == @advance_on
+
+          @cursor += 1
+        end
+        finish(@advance_on)
+      end
+
+      def finish(status)
+        @cursor = 0
+        status
+      end
+
+      def stop(run)
+        halt_all(@children, run)
+        @cursor = 0
+      end
+
+      def running_deadline = earliest(@children.map(&:next_deadline))
+    end
+
+    # ReactiveSequence and ReactiveFallback: re-walk from the first child.
+    class ReactiveSlot < Slot
+      def initialize(id, children, advance_on)
+        super(id)
+        @children = children
+        @advance_on = advance_on
+      end
+
+      private
+
+      def step(run, now, _starting)
+        @children.each_with_index do |child, index|
+          status = child.tick(run, now)
+          next if status == @advance_on
+
+          halt_all(@children.drop(index + 1), run)
+          return status
+        end
+        @advance_on
+      end
+
+      def stop(run) = halt_all(@children, run)
+      def running_deadline = earliest(@children.map(&:next_deadline))
+    end
+
+    class ParallelSlot < Slot
+      def initialize(id, children, success, failure)
+        super(id)
+        @children = children
+        @success = success
+        @failure = failure
+        @outcomes = Array.new(children.size)
+      end
+
+      private
+
+      def step(run, now, _starting)
+        decided = decide(run, now)
+        return :running unless decided
+
+        halt_all(@children, run)
+        @outcomes.fill(nil)
+        decided
+      end
+
+      # Children decide in order, so the leftmost wins ties.
+      def decide(run, now)
+        succeeded = @outcomes.count(:success)
+        failed = @outcomes.count(:failure)
+        @children.each_with_index do |child, index|
+          next if @outcomes[index]
+
+          status = child.tick(run, now)
+          next if status == :running
+
+          @outcomes[index] = status
+          status == :success ? succeeded += 1 : failed += 1
+          return :success if succeeded >= @success
+          return :failure if failed >= @failure || @children.size - failed < @success
+        end
+        nil
+      end
+
+      def stop(run)
+        halt_all(@children, run)
+        @outcomes.fill(nil)
+      end
+
+      def running_deadline = earliest(@children.map(&:next_deadline))
+    end
+
+    # Shared by IfThenElse and WhileDoElse.
+    class ConditionalSlot < Slot
+      def initialize(id, condition, branch, otherwise)
+        super(id)
+        @condition = condition
+        @branch = branch
+        @otherwise = otherwise
+      end
+
+      private
+
+      def stop(run)
+        [@condition, @branch, @otherwise].compact.each { |slot| slot.halt(run) }
+      end
+
+      def running_deadline = earliest([@condition, @branch, @otherwise].compact.map(&:next_deadline))
+    end
+
+    class IfThenElseSlot < ConditionalSlot
+      def initialize(...)
+        super
+        @selected = nil
+      end
+
+      private
+
+      def step(run, now, _starting)
+        unless @selected
+          case @condition.tick(run, now)
+          when :running then return :running
+          when :success then @selected = :branch
+          else @selected = :otherwise
+          end
+        end
+        chosen = @selected == :branch ? @branch : @otherwise
+        return finish(:failure) unless chosen
+
+        status = chosen.tick(run, now)
+        status == :running ? status : finish(status)
+      end
+
+      def finish(status)
+        @selected = nil
+        status
+      end
+
+      def stop(run)
+        super
+        @selected = nil
+      end
+    end
+
+    # While the condition runs the branches are paused: neither ticked nor
+    # halted. Otherwise the unselected branch is halted before the other ticks.
+    class WhileDoElseSlot < ConditionalSlot
+      private
+
+      def step(run, now, _starting)
+        case @condition.tick(run, now)
+        when :running then :running
+        when :success
+          @otherwise&.halt(run)
+          @branch.tick(run, now)
+        else
+          @branch.halt(run)
+          @otherwise ? @otherwise.tick(run, now) : :failure
+        end
+      end
+
+      # A paused branch's timers cannot act until the condition finishes.
+      def running_deadline = @condition.running? ? @condition.next_deadline : super
+    end
+
+    # Inverter, ForceSuccess, and ForceFailure.
+    class MapSlot < Slot
+      def initialize(id, child, map)
+        super(id)
+        @child = child
+        @map = map
+      end
+
+      private
+
+      def step(run, now, _starting)
+        status = @child.tick(run, now)
+        return status if status == :running
+
+        case @map
+        when :inverter then status == :success ? :failure : :success
+        when :force_success then :success
+        else :failure
+        end
+      end
+
+      def stop(run) = @child.halt(run)
+      def running_deadline = @child.next_deadline
+    end
+
+    # The child only ticks strictly before the deadline.
+    class TimeoutSlot < Slot
+      def initialize(id, nanos, child)
+        super(id)
+        @nanos = nanos
+        @child = child
+        @deadline = nil
+      end
+
+      private
+
+      def step(run, now, starting)
+        @deadline = Engine.deadline_after(now, @nanos) if starting
+        if Engine.reached?(@deadline, now)
+          @child.halt(run)
+          return :failure
+        end
+        @child.tick(run, now)
+      end
+
+      def stop(run) = @child.halt(run)
+      def running_deadline = earliest([@deadline, @child.next_deadline])
+    end
+
+    # Repeat, RetryUntilSuccessful, and KeepRunningUntilFailure: at most one
+    # finished child run per tick.
+    class LoopSlot < Slot
+      def initialize(id, child, again_on, limit)
+        super(id)
+        @child = child
+        @again_on = again_on
+        @limit = limit
+        @runs = 0
+      end
+
+      private
+
+      def step(run, now, _starting)
+        return @again_on if @limit&.zero?
+
+        status = @child.tick(run, now)
+        return status if status == :running
+        return finish(status) unless status == @again_on
+        return :running if @limit.nil?
+        return finish(status) if @runs + 1 == @limit
+
+        @runs += 1
+        :running
+      end
+
+      def finish(status)
+        @runs = 0
+        status
+      end
+
+      def stop(run)
+        @child.halt(run)
+        @runs = 0
+      end
+
+      def running_deadline = @child.next_deadline
+    end
+  end
+end

data/lib/behavior_machines/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BehaviorMachines
+  # Base class for errors raised by this library.
+  class Error < StandardError; end
+
+  # A node definition cannot be compiled into a tree.
+  class BuildError < Error; end
+
+  # A leaf's tick returned something other than :success, :failure, or :running.
+  class InvalidStatusError < Error; end
+
+  # A leaf called Tree#tick or Tree#halt on the tree that is ticking it.
+  class ReentrantCallError < Error; end
+end

data/lib/behavior_machines/machine.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module BehaviorMachines
+  # Leaves that drive objects powered by the state_machines gem, through the
+  # helpers it generates for every machine: `<machine>_name` and
+  # `fire_<machine>_event`.
+  #
+  # Each leaf finds its object in the tree context with `access`: a Symbol
+  # naming a method on the context, or anything responding to call(ctx).
+  module Machine
+    def self.accessor(access)
+      case access
+      when Symbol, String then ->(ctx) { ctx.public_send(access) }
+      else
+        raise ArgumentError, "access must be a Symbol or respond to call, got #{access.inspect}" unless access.respond_to?(:call)
+
+        access
+      end
+    end
+
+    # Succeeds while the machine is in one of `states`, fails otherwise.
+    class InState
+      def initialize(access, *states, machine: :state)
+        raise ArgumentError, 'InState needs at least one state' if states.empty?
+
+        @access = Machine.accessor(access)
+        @states = states.map(&:to_sym).freeze
+        @reader = :"#{machine}_name"
+      end
+
+      def tick(ctx, _now) = @states.include?(@access.call(ctx).public_send(@reader)) ? :success : :failure
+    end
+
+    # Fires `event` each tick: succeeds if the machine accepts it, fails if it
+    # is rejected.
+    class Fire
+      def initialize(access, event, machine: :state)
+        @access = Machine.accessor(access)
+        @event = event.to_sym
+        @fire = :"fire_#{machine}_event"
+      end
+
+      def tick(ctx, _now) = @access.call(ctx).public_send(@fire, @event) ? :success : :failure
+    end
+
+    # Waits on a machine something else drives: succeeds in a `success` state,
+    # fails in a `failure` state, runs otherwise. If the tree abandons it,
+    # fires `on_halt` (typically :cancel).
+    class WaitFor
+      def initialize(access, success:, failure: [], on_halt: nil, machine: :state)
+        @access = Machine.accessor(access)
+        @success = Array(success).map(&:to_sym).freeze
+        @failure = Array(failure).map(&:to_sym).freeze
+        @on_halt = on_halt&.to_sym
+        @reader = :"#{machine}_name"
+        @fire = :"fire_#{machine}_event"
+      end
+
+      def tick(ctx, _now)
+        state = @access.call(ctx).public_send(@reader)
+        return :success if @success.include?(state)
+        return :failure if @failure.include?(state)
+
+        :running
+      end
+
+      # A rejected event means the machine already left the states that accept
+      # it, e.g. a job that completed after the last tick. The tree abandons
+      # the leaf either way, so the result is deliberately ignored.
+      def halt(ctx)
+        @access.call(ctx).public_send(@fire, @on_halt) if @on_halt
+        nil
+      end
+    end
+  end
+end

data/lib/behavior_machines/native_extension.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+
+module BehaviorMachines
+  # Loads the optional native backend. It is opt-in: set
+  # BEHAVIOR_MACHINES_NATIVE=1 before requiring behavior_machines.
+  module NativeExtension
+    class << self
+      # Why the last load attempt failed, if it did.
+      attr_reader :error
+
+      def load!
+        return @loaded if defined?(@loaded)
+        return @loaded = false unless ENV['BEHAVIOR_MACHINES_NATIVE'] == '1'
+
+        errors = []
+        candidates.each do |path|
+          require path
+          return @loaded = true
+        rescue LoadError => e
+          errors << "#{path}: #{e.message}"
+        end
+        @error = errors.join(' | ')
+        @loaded = false
+      end
+
+      def loaded? = load!
+
+      private
+
+      # Prefer a build matching this Ruby version and platform.
+      def candidates
+        dlext = RbConfig::CONFIG['DLEXT']
+        root = File.expand_path('..', __dir__)
+        builds = Dir.glob(File.join(root, 'behavior_machines_native', '**', "behavior_machines_native.#{dlext}"))
+        ranked = builds.sort_by do |path|
+          score = 0
+          score -= 2 if path.include?(RbConfig::CONFIG['ruby_version'])
+          score -= 1 if path.include?(RbConfig::CONFIG['arch'])
+          [score, path]
+        end
+        paths = ranked.map { |path| path.delete_prefix("#{root}/").delete_suffix(".#{dlext}") }
+        (paths + ['behavior_machines_native/behavior_machines_native']).uniq
+      end
+    end
+  end
+end

data/lib/behavior_machines/node.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module BehaviorMachines
+  # Immutable node definitions. Build them with the module functions on
+  # BehaviorMachines (BehaviorMachines.sequence, .parallel, ...) and the
+  # decorator methods every node responds to, then compile with Tree.new.
+  #
+  # Names and semantics follow the behavior-tree pattern, matching the
+  # behavior-machines Rust crate.
+  module Node
+    # Decorators available on every node.
+    module Decorators
+      def inverter = Inverter.new(child: self)
+      def force_success = ForceSuccess.new(child: self)
+      def force_failure = ForceFailure.new(child: self)
+      def timeout(seconds) = Timeout.new(seconds:, child: self)
+      def repeat(limit) = Repeat.new(limit:, child: self)
+      def retry_until_successful(limit) = RetryUntilSuccessful.new(limit:, child: self)
+      def keep_running_until_failure = KeepRunningUntilFailure.new(child: self)
+    end
+
+    def self.define(*members) = Data.define(*members) { include Decorators }
+    private_class_method :define
+
+    Leaf = define(:leaf)
+    AlwaysSuccess = define
+    AlwaysFailure = define
+    Sleep = define(:seconds)
+    Sequence = define(:children)
+    ReactiveSequence = define(:children)
+    Fallback = define(:children)
+    ReactiveFallback = define(:children)
+    Parallel = define(:children, :success, :failure)
+    IfThenElse = define(:condition, :then_branch, :otherwise)
+    WhileDoElse = define(:condition, :body, :otherwise)
+    Inverter = define(:child)
+    ForceSuccess = define(:child)
+    ForceFailure = define(:child)
+    Timeout = define(:seconds, :child)
+    Repeat = define(:limit, :child)
+    RetryUntilSuccessful = define(:limit, :child)
+    KeepRunningUntilFailure = define(:child)
+  end
+
+  class << self
+    # A condition check or action: any object responding to tick(ctx, now)
+    # and, optionally, halt(ctx).
+    def leaf(leaf) = Node::Leaf.new(leaf:)
+
+    # Succeeds immediately.
+    def always_success = Node::AlwaysSuccess.new
+
+    # Fails immediately.
+    def always_failure = Node::AlwaysFailure.new
+
+    # Runs until `seconds` have passed since it started, then succeeds.
+    def sleep(seconds) = Node::Sleep.new(seconds:)
+
+    # Ticks children in order; fails on the first failure, succeeds once all
+    # succeed. A running child is resumed on the next tick.
+    def sequence(*children) = Node::Sequence.new(children: children.freeze)
+
+    # A sequence that restarts from its first child every tick, halting a
+    # running later child once an earlier one stops succeeding.
+    def reactive_sequence(*children) = Node::ReactiveSequence.new(children: children.freeze)
+
+    # Ticks children in order; succeeds on the first success, fails once all
+    # fail. A running child is resumed on the next tick.
+    def fallback(*children) = Node::Fallback.new(children: children.freeze)
+
+    # A fallback that restarts from its first child every tick, so a
+    # higher-priority child preempts (halts) a running lower-priority one.
+    def reactive_fallback(*children) = Node::ReactiveFallback.new(children: children.freeze)
+
+    # Ticks every unfinished child each tick. Succeeds once `success` children
+    # succeeded; fails once `failure` failed or success became unreachable.
+    # Thresholds are :all or an Integer; by default every child must succeed
+    # and one failure fails the node.
+    def parallel(*children, success: :all, failure: 1)
+      Node::Parallel.new(children: children.freeze, success:, failure:)
+    end
+
+    # Ticks `condition` until it finishes, then runs `then_branch` or
+    # `otherwise`. Without `otherwise`, a failed condition fails the node.
+    def if_then_else(condition, then_branch, otherwise = nil)
+      Node::IfThenElse.new(condition:, then_branch:, otherwise:)
+    end
+
+    # The reactive if_then_else: re-checks `condition` every tick, pausing the
+    # branches while it runs and halting the unselected branch when it flips.
+    def while_do_else(condition, body, otherwise = nil)
+      Node::WhileDoElse.new(condition:, body:, otherwise:)
+    end
+  end
+end

data/lib/behavior_machines/tree.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module BehaviorMachines
+  # A compiled behavior tree and its execution state.
+  #
+  # Each tick advances as far as the leaves allow; looping decorators finish
+  # at most one child run per tick. When the tree abandons a running node,
+  # every active leaf under it is halted exactly once before the call returns.
+  #
+  # Leaves are objects responding to `tick(ctx, now)`, returning :success,
+  # :failure, or :running, and optionally `halt(ctx)`.
+  #
+  # If a leaf or observer raises during a tick, the rest of that tick runs no
+  # leaf code (active leaves stay active, idle ones do not start), every leaf
+  # still active is then halted without observer reports, and the first error
+  # propagates. The raising leaf counts as finished. During a halt, every
+  # active leaf is halted even if a leaf's halt or the observer raises; the
+  # first error propagates afterwards. Non-local exits from a leaf, such as
+  # `throw` or `break`, are not supported.
+  #
+  # Time is an Integer count of nanoseconds on a monotonic clock, passed as
+  # `now:` (default BehaviorMachines.now). Durations in node definitions are
+  # seconds.
+  class Tree
+    attr_reader :backend
+
+    # Compiles `root`. `backend:` is :ruby, :native, or :auto (native when the
+    # extension is loaded, see BehaviorMachines.native_available?).
+    def initialize(root, backend: :auto)
+      spec = Definition.compile(root)
+      @backend = BehaviorMachines.resolve_backend(backend)
+      @engine = @backend == :native ? BehaviorMachinesNative::Tree.new(spec) : Engine::Tree.new(spec)
+      @busy = false
+    end
+
+    # Ticks once and returns the root's status. `observer` may respond to
+    # `ticked(node_id, status)` and `halted(node_id)`; node ids number the
+    # definition in pre-order, and children report before their parent.
+    def tick(ctx = nil, now: BehaviorMachines.now, observer: nil)
+      now = BehaviorMachines.check_time(now)
+      exclusive { @engine.tick(ctx, now, Observers.wrap(observer)) }
+    end
+
+    # Halts every active leaf and resets the tree. Does nothing if not running.
+    def halt(ctx = nil, observer: nil)
+      exclusive { @engine.halt(ctx, Observers.wrap(observer)) }
+      nil
+    end
+
+    # Whether the last tick returned :running and the tree was not halted since.
+    def running?
+      check_idle
+      @engine.running?
+    end
+
+    # The earliest time, in nanoseconds, a running Sleep or Timeout will fire.
+    def next_deadline
+      check_idle
+      @engine.next_deadline
+    end
+
+    private
+
+    def check_idle
+      raise ReentrantCallError, 'a leaf called back into the tree that is ticking it' if @busy
+    end
+
+    def exclusive
+      check_idle
+
+      begin
+        @busy = true
+        yield
+      ensure
+        @busy = false
+      end
+    end
+  end
+
+  # Normalizes user observers so engines can call both hooks unconditionally.
+  module Observers
+    # Forwards only the hooks the wrapped observer implements.
+    Partial = Data.define(:target) do
+      def ticked(id, status) = (target.ticked(id, status) if target.respond_to?(:ticked))
+      def halted(id) = (target.halted(id) if target.respond_to?(:halted))
+    end
+
+    def self.wrap(observer)
+      return nil if observer.nil?
+      return observer if observer.respond_to?(:ticked) && observer.respond_to?(:halted)
+
+      Partial.new(observer)
+    end
+  end
+end

data/lib/behavior_machines/version.rb

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

data/lib/behavior_machines.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'behavior_machines/version'
+require_relative 'behavior_machines/errors'
+require_relative 'behavior_machines/node'
+require_relative 'behavior_machines/definition'
+require_relative 'behavior_machines/engine'
+require_relative 'behavior_machines/tree'
+require_relative 'behavior_machines/machine'
+require_relative 'behavior_machines/native_extension'
+
+# Behavior trees with explicit halt semantics, following the behavior-tree
+# pattern. Pure Ruby, with an optional native backend built on the behavior-machines Rust crate.
+module BehaviorMachines
+  STATUSES = %i[success failure running].freeze
+
+  class << self
+    # The current monotonic time in nanoseconds.
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+
+    # Whether the native backend is loaded (opt-in, see NativeExtension).
+    def native_available? = NativeExtension.loaded?
+
+    def resolve_backend(backend)
+      case backend
+      when :ruby then :ruby
+      when :auto then native_available? ? :native : :ruby
+      when :native
+        return :native if native_available?
+
+        raise Error, "native backend not loaded (set BEHAVIOR_MACHINES_NATIVE=1#{"; #{NativeExtension.error}" if NativeExtension.error})"
+      else raise ArgumentError, "backend must be :ruby, :native, or :auto, got #{backend.inspect}"
+      end
+    end
+
+    def check_status(status, leaf)
+      return status if STATUSES.include?(status)
+
+      raise InvalidStatusError, "#{leaf.inspect} returned #{status.inspect}; expected :success, :failure, or :running"
+    end
+
+    def check_time(now)
+      return now if now.is_a?(Integer) && now.between?(0, Definition::MAX_NANOS)
+
+      raise ArgumentError, "now must be an Integer number of nanoseconds in 0..2**64-1, got #{now.inspect}"
+    end
+  end
+end
+
+BehaviorMachines::NativeExtension.load!

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: behavior_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: arm64-darwin
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: state_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.202'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.202'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: |
+  BehaviorMachines runs behavior trees whose nodes follow the behavior-tree pattern: Sequence,
+  Fallback, their reactive variants, thresholded Parallel,
+  IfThenElse, WhileDoElse, and the usual decorators. Every running leaf the tree abandons is halted
+  exactly once, in the same call, so leaves can own real resources. Pure Ruby, with an optional
+  native backend built on the behavior-machines Rust crate, and leaves for state_machines objects.
+email:
+- terminale@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/behavior_machines.rb
+- lib/behavior_machines/definition.rb
+- lib/behavior_machines/engine.rb
+- lib/behavior_machines/errors.rb
+- lib/behavior_machines/machine.rb
+- lib/behavior_machines/native_extension.rb
+- lib/behavior_machines/node.rb
+- lib/behavior_machines/tree.rb
+- lib/behavior_machines/version.rb
+- lib/behavior_machines_native/behavior_machines_native.bundle
+homepage: https://github.com/seuros/behavior-machines
+licenses:
+- BSD-3-Clause
+metadata:
+  homepage_uri: https://github.com/seuros/behavior-machines
+  source_code_uri: https://github.com/seuros/behavior-machines
+  bug_tracker_uri: https://github.com/seuros/behavior-machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: behavior_machines_native
+  cargo_manifest_path: ext/behavior_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: Behavior trees with explicit halt semantics, following the behavior-tree
+  pattern
+test_files: []