statifier 0.0.1 → 0.1.0

data/lib/statifier/interpreter/invoke.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Interpreter
+    # The invoke passes, as the reference ports them
+    # (`run_invoke_pass`, `invoke_one`, `generate_invoke_id`,
+    # `apply_invoke_passes`, `apply_finalize` and `auto_assign_finalize` in
+    # `Statifier.Interpreter`, and `cancel_invocations_for_state` in
+    # `Statifier.Interpreter.ExitEntry`, statifier-ex): starting the
+    # invocations of the states a macrostep entered, the finalize and
+    # autoforward pass an external event meets before its selection, and the
+    # cancel of a state's live invocations as it exits.
+    #
+    # The core starts no service. Starting an invocation answers an
+    # {Effect::Invoke} and records it live in the state's
+    # `active_invocations`; forwarding an event answers an
+    # {Effect::Autoforward} carrying the event whole; a state that exits
+    # answers an {Effect::CancelInvoke} per live invocation it owns. Running
+    # the service, delivering to it and turning what it answers into events
+    # are the driver's. An event an invocation sent is an ordinary external
+    # event here: its `invokeid` decides only which `<finalize>` runs.
+    #
+    # No host declares the invoke types it runs, so every invocation is
+    # judged as the reference judges one in a session that declared none:
+    # the effect is answered for any type, and only the built-in SCXML type
+    # ({built_in_type?}) is recorded live.
+    #
+    # @api private
+    module Invoke
+      # The URI of the SCXML invoke type.
+      SCXML_TYPE = "http://www.w3.org/TR/scxml/"
+
+      # The spellings of the built-in type: none, the short form, and the
+      # URI with and without its trailing slash.
+      BUILT_IN_TYPES = [nil, "scxml", SCXML_TYPE, SCXML_TYPE.chomp("/")].freeze
+
+      module_function
+
+      # Whether the SCXML processor runs an invocation of `type` itself.
+      def built_in_type?(type) = BUILT_IN_TYPES.include?(type)
+
+      # `for state in statesToInvoke.sort(entryOrder): for inv in
+      # state.invoke.sort(documentOrder): invoke(inv)`, then
+      # `statesToInvoke.clear()`, with its {Effect::Trace::InvokePass} last.
+      # One context is threaded through the pass, so an invocation's
+      # arguments read an id an earlier one wrote to its `idlocation`. An
+      # invocation whose start fails raises `error.execution` and answers
+      # nothing; its siblings are unaffected.
+      #
+      # @return [Array] `[state, effects]`
+      def invoke_pass(state)
+        order = state.states_to_invoke
+        passed, _context, effects = order.reduce([state, state.context, []]) do |acc, index|
+          state.machine.state(index).invoke.reduce(acc) { |inner, invoke| invoke_one(inner, index, invoke) }
+        end
+        invoke_ids = live_ids(passed, effects)
+        trace = Blocks.traced(passed, Effect::Trace::InvokePass, state_indexes: order, invoke_ids:)
+        [passed.with(states_to_invoke: [].freeze), effects + trace]
+      end
+
+      # The ids of the invocations the pass left live, in the order it
+      # started them.
+      def live_ids(state, effects)
+        effects.grep(Effect::Invoke).select { state.active_invocations[key(_1)] == _1.invoke_id }.map(&:invoke_id)
+      end
+
+      # The key an invocation is live under.
+      def key(effect) = [effect.state_index, effect.invoke_index].freeze
+
+      # `invoke(inv)`: the type, the source, the `namelist` and `<param>`
+      # values in order, then `<content>`, the first failure abandoning this
+      # invocation; then the id minted or read, `idlocation` written, the
+      # invocation recorded live for the built-in type, and the effect,
+      # after the write's {Effect::DatamodelChange}.
+      #
+      # @return [Array] `[state, context, effects]`
+      def invoke_one((state, context, effects), index, invoke)
+        origin = { kind: :invoke, state_index: index, invoke_index: invoke.index }
+        resolved = Arguments.resolve(context, invoke)
+        return [state.raise_failure(origin, resolved), context, effects] unless resolved.is_a?(Hash)
+
+        state, invoke_id = mint(state, index, invoke)
+        write = invoke.idlocation && Datamodel::Location.write(context, invoke.idlocation, invoke_id)
+        return [state.raise_failure(origin, write.error), context, effects] if write && !write.ok?
+
+        started(state, (write ? write.context : context), effects, invoke, resolved.merge(origin, invoke_id:, write:))
+      end
+
+      # An invocation whose arguments resolved and whose id is written:
+      # recorded live for the built-in type, its effects answered.
+      def started(state, context, effects, invoke, fields)
+        state = state.with(datamodel: Ractor.make_shareable(context.data))
+        state = record(state, fields) if built_in_type?(fields[:type])
+        [state, context, effects + changes(state, invoke, fields) + [effect(state, invoke, fields)]]
+      end
+
+      # The state with the invocation live under its key.
+      def record(state, fields)
+        key = [fields[:state_index], fields[:invoke_index]].freeze
+        state.with(active_invocations: state.active_invocations.merge(key => -fields[:invoke_id]).freeze)
+      end
+
+      # The {Effect::Invoke}.
+      def effect(state, invoke, fields)
+        Frozen.copy(Effect::Invoke.new(
+                      **fields.slice(:invoke_id, :type, :src, :params, :content, :state_index, :invoke_index),
+                      autoforward: invoke.autoforward, **state.counters, caller_context: state.caller_context
+                    ))
+      end
+
+      # The `idlocation` write's {Effect::DatamodelChange}, when there was
+      # one.
+      def changes(state, invoke, fields)
+        write = fields[:write]
+        return [] unless write
+
+        [change(state, write, invoke.idlocation, fields[:invoke_id], fields.slice(:kind, :state_index, :invoke_index))]
+      end
+
+      # A write no content node made, owned by the invocation (`{kind:
+      # :invoke, ...}`) or by its empty `<finalize>` (`{kind: :finalize,
+      # ...}`).
+      def change(state, write, source, value, owner)
+        Frozen.copy(Effect::DatamodelChange.new(
+                      location_path: write.path, location_source: source, new_value: value,
+                      prior_value: write.prior_value, d_index: nil, c_index: nil, owner:, **state.counters
+                    ))
+      end
+
+      # `generate_invoke_id`: the author's id, which consumes no counter;
+      # else `inv_` and the counter plus one, after the state's id and a dot
+      # when the state has one. `[state, invoke_id]`.
+      def mint(state, index, invoke)
+        return [state, invoke.id] unless invoke.id.nil?
+
+        counter = state.invoke_counter + 1
+        owner = state.machine.state(index).id
+        [state.with(invoke_counter: counter), owner.nil? ? "inv_#{counter}" : "#{owner}.inv_#{counter}"]
+      end
+    end
+  end
+end
+
+require_relative "invoke/arguments"
+require_relative "invoke/passes"

data/lib/statifier/interpreter/loop.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Interpreter
+    # What {Loop.handle_event} and {Loop.deliver_internal} answered: the
+    # {MachineState} and effects of the step, or, as `error`,
+    # `:not_running` for a chart that has stopped, with the state given
+    # back unchanged and no effects.
+    #
+    # @api private
+    Handled = ::Data.define(:state, :effects, :error) do
+      # @return [Boolean] whether the step ran
+      def ok? = error.nil?
+    end
+
+    # The specification's `interpret` and `mainEventLoop`, ported as the
+    # reference ports them (`Statifier.Interpreter` in statifier-ex): three
+    # entry points over a {MachineState}, each answering the state it leaves
+    # with its effects. {initialize} starts a chart, {handle_event} takes one
+    # external event and {deliver_internal} queues one event on the internal
+    # queue (the driver's door for a send to `#_internal`, or for a delivery
+    # failure it found); each then runs the macrostep ({Macrostep}) to a
+    # stable configuration, or to the chart stopping ({Stop}).
+    #
+    # The outer `while running` loop is the caller's, as in the reference:
+    # the core takes one external event per call, and the driver keeps the
+    # external events still waiting.
+    #
+    # Starting a chart answers {Effect::DatamodelInit} first, then a
+    # {Effect::DatamodelChange} per `<data>` that binds. With the state's
+    # `trace` set, the loop answers the reference's trace effects in its
+    # order.
+    #
+    # Before an external event's selection the finalize and autoforward
+    # pass runs over the live invocations ({Invoke::Passes}); {cancel} is
+    # the specification's cancel path, which stops a running chart.
+    #
+    # @api private
+    module Loop
+      module_function
+
+      # `interpret`: a fresh {MachineState} over `machine` (the options are
+      # {MachineState.fresh}'s), its datamodel initialized, the `<script>`
+      # children of `<scxml>` run in document order, the initial states
+      # entered and the macrostep run. This is macrostep 1, and the initial
+      # entry its microstep 1. `clock` is the host's clock for the call.
+      #
+      # @return [Stepped]
+      def self.initialize(machine, session_id:, clock: nil, **)
+        state = MachineState.fresh(machine, session_id:, **).begin_macrostep.begin_microstep.with(clock:)
+        bound = initialize_datamodel(state)
+        scripts = bound.then_step(run_global_scripts(bound.state))
+        entered = scripts.then_step(Step.enter_states(scripts.state, [initial_transition(machine)]))
+        entered.then_step(Macrostep.main_event_loop(entered.state))
+      end
+
+      # `mainEventLoop`'s external-event body: a new macrostep stamped with
+      # the event's `caller_context`, `_event` set, the transitions the
+      # event enables selected and taken, then the macrostep run. The
+      # answered state's `last_selection` says whether the event selected a
+      # transition. `event` is an {Event}, copied before it is frozen except
+      # its `caller_context`, which the state carries as the same object.
+      #
+      # @return [Handled]
+      def handle_event(state, event, clock: nil)
+        return Handled.new(state:, effects: [], error: :not_running) unless state.running
+
+        event = Frozen.copy(event)
+        state = state.begin_macrostep.with(caller_context: event.caller_context, clock:)
+        dequeued = Blocks.traced(state, Effect::Trace::EventDequeued, event:, from: :external)
+        taken = take(state.put_event(event), event)
+        Handled.new(state: taken.state, effects: dequeued + taken.effects, error: nil)
+      end
+
+      # The finalize and autoforward pass, the event's selection and
+      # the macrostep after it, with `last_selection` written.
+      #
+      # @return [Stepped]
+      def take(state, event)
+        state, passes = Invoke::Passes.finalize_autoforward(state, event)
+        state, transitions, conds = Macrostep.select(state, event)
+        ran = Macrostep.run_selected(state, transitions, event)
+        looped = ran.then_step(Macrostep.main_event_loop(ran.state))
+        Stepped.new(state: looped.state.with(last_selection: transitions.empty? ? :none : :selected),
+                    effects: passes + conds + looped.effects)
+      end
+
+      # `mainEventLoop`'s cancel path: `running` cleared, then
+      # `exitInterpreter` ({Stop.exit_interpreter}), with no caller context,
+      # since a cancel has no sending caller. A stopped chart answers
+      # `:not_running`, its state unchanged.
+      #
+      # @return [Handled]
+      def cancel(state)
+        return Handled.new(state:, effects: [], error: :not_running) unless state.running
+
+        exited = Stop.exit_interpreter(state.with(running: false, caller_context: nil))
+        Handled.new(state: exited.state, effects: exited.effects, error: nil)
+      end
+
+      # The door back onto the internal queue: one event of `kind`
+      # (`:internal` or `:platform`) named `name`, its cause `origin` and
+      # the counters as they stand, queued as an in-loop raise would queue
+      # it, then the macrostep run. `options` are the event's `data:` and
+      # `sendid:`, and `clock:`, the host's clock for the call. The driver
+      # routes a send to `#_internal` here, and an `error.communication` for
+      # a send it could not deliver.
+      #
+      # @return [Handled]
+      def deliver_internal(state, kind, name, origin, **options)
+        return Handled.new(state:, effects: [], error: :not_running) unless state.running
+
+        raised = state.with(clock: options[:clock])
+                      .public_send(kind == :internal ? :raise_internal : :raise_platform, name, origin,
+                                   **options.except(:clock))
+        looped = Macrostep.main_event_loop(raised)
+        Handled.new(state: looped.state, effects: looped.effects, error: nil)
+      end
+
+      # The datamodel initialized: {Effect::DatamodelInit} with every
+      # `<data>` id declared, then the binding of what binds when the chart
+      # starts ({Datamodel::DataBinding.start}).
+      #
+      # @return [Stepped]
+      def initialize_datamodel(state)
+        context = state.context
+        init = Effect::DatamodelInit.new(datamodel: Datamodel::DataBinding.seed(context), **state.counters)
+        Stepped.new(state:, effects: [Frozen.copy(init)])
+               .then_step(Blocks.bound(state, Datamodel::DataBinding.start(context)))
+      end
+
+      # `executeGlobalScriptElement`: each `<script>` child of `<scxml>` in
+      # document order against the datamodel the one before it left. A
+      # script that did not compile, or whose run fails, raises
+      # `error.execution` (origin `{kind: :global_script, index:}`), keeping
+      # what a failing run wrote. Each answers a
+      # {Effect::Trace::ContentExecuted} naming no node.
+      #
+      # @return [Stepped]
+      def run_global_scripts(state)
+        state.machine.global_scripts.each_with_index.reduce(Stepped.new(state:, effects: [])) do |acc, (script, index)|
+          acc.then_step(run_global_script(acc.state, script, { kind: :global_script, index: }))
+        end
+      end
+
+      # One `<script>` child of `<scxml>`, as {run_global_scripts}.
+      #
+      # @return [Stepped]
+      def run_global_script(state, script, origin)
+        executed = Datamodel.execute(state.context, script)
+        after = state.with(datamodel: Ractor.make_shareable(executed.data))
+        after = after.raise_failure(origin, executed.error) unless executed.ok?
+        Stepped.new(state: after, effects: Blocks.traced(after, Effect::Trace::ContentExecuted, owner: origin,
+                                                                                                c_indexes: []))
+      end
+
+      # The root's `<initial>` transition, or the one the reference
+      # synthesizes from the root's default targets; a synthesized
+      # transition is no document element and has no index.
+      def initial_transition(machine)
+        root = machine.state(0)
+        return machine.transitions.fetch(root.initial_transition) unless root.initial_transition.nil?
+
+        Machine::Transition.new(t_index: nil, source: 0, targets: root.initial, events: [].freeze, cond: nil,
+                                type: :external, content: [].freeze, location: machine.location, cond_location: nil,
+                                attribute_locations: {}.freeze)
+      end
+    end
+  end
+end

data/lib/statifier/interpreter/machine_state.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Interpreter
+    # The interpreter's position, as the reference keeps it
+    # (`Statifier.MachineState` in statifier-ex): every global and loop
+    # variable of the specification's pseudocode as one immutable value, so
+    # a position between two calls is data and never a stack frame. Every
+    # function of the loop takes one and answers the one it leaves.
+    #
+    # The fields: `machine`; `configuration`, the active state indexes, a
+    # frozen ascending Array; `history`, the recorded value of each history
+    # state that has one; `datamodel`; `internal_queue`, the queued
+    # {Event}s, oldest first; `entered_states`, every state ever entered
+    # (a state's own `<data>` binds on its first entry under late binding);
+    # `states_to_invoke`, the states entered since the last invoke pass;
+    # `sends`, the {Send::SendState}; `caller_context`, the opaque value the
+    # host attached to the event the current macrostep handles, nil for
+    # none; `clock`, the host's clock for the current call, nil for
+    # predicator's own; `last_selection`, `:selected` or `:none` for the
+    # last external event, nil before one; `running`, false once a
+    # top-level final is entered; `status`, `:running`, or `:done` once the
+    # chart has stopped; the counters `macrostep`, `microstep` and `round`;
+    # `trace`, whether the loop answers trace effects;
+    # `max_macrostep_rounds`, the round budget, a positive Integer or
+    # `:infinity`; `active_invocations`, the live invocations, a frozen Hash
+    # of `[state_index, invoke_index]` to the invocation's id; and
+    # `invoke_counter`, the sequence a generated invoke id is minted from.
+    # The invoke pass ({Invoke.invoke_pass}) records an invocation of the
+    # built-in type there, and the cancel of its state removes it.
+    #
+    # The counters: `macrostep` advances once when the chart starts and once
+    # per external event, and starts the other two over; `microstep`
+    # advances once per microstep that exits and enters (the initial entry is
+    # microstep 1); `round` once per pass of the macrostep's loop, a pass
+    # that moves nothing included.
+    #
+    # @api private
+    MachineState = ::Data.define(
+      :machine, :configuration, :history, :datamodel, :internal_queue, :entered_states, :states_to_invoke,
+      :sends, :caller_context, :clock, :last_selection, :running, :status, :macrostep, :microstep, :round,
+      :trace, :max_macrostep_rounds, :active_invocations, :invoke_counter
+    ) do
+      # The {Snapshot} selection, exit and entry read.
+      def snapshot = Snapshot.new(machine:, configuration:, history:)
+
+      # The {Datamodel::Context} an evaluation site runs against now.
+      def context = Datamodel.context(datamodel, machine, configuration, clock:)
+
+      # The counters as they stand.
+      def counters = { macrostep:, microstep:, round: }
+
+      # The {Event::Cause} of an event raised now about `origin`.
+      def cause(origin) = Event::Cause.new(origin:, **counters)
+
+      # A new macrostep: the other two counters start over.
+      def begin_macrostep = with(macrostep: macrostep + 1, microstep: 0, round: 0)
+
+      # The next microstep.
+      def begin_microstep = with(microstep: microstep + 1)
+
+      # The next round.
+      def begin_round = with(round: round + 1)
+
+      # The state with `events` queued, in order.
+      def enqueue(*events) = with(internal_queue: (internal_queue + events).freeze)
+
+      # The state with a platform event named `name` queued, its cause
+      # `origin` and the counters as they stand.
+      def raise_platform(name, origin, data: Predicator::UNDEFINED, sendid: nil)
+        enqueue(Frozen.copy(Event.platform(name, cause(origin), data:, sendid:)))
+      end
+
+      # The state with an `error.execution` queued about `origin`, its data
+      # the failure `reason` as a predicator value
+      # ({Datamodel::ReasonValue.of}).
+      def raise_failure(origin, reason)
+        raise_platform("error.execution", origin, data: Datamodel::ReasonValue.of(reason))
+      end
+
+      # The state with an internal event queued, as {raise_platform}.
+      def raise_internal(name, origin, data: Predicator::UNDEFINED, sendid: nil)
+        enqueue(Frozen.copy(Event.internal(name, cause(origin), data:, sendid:)))
+      end
+
+      # The oldest queued event and the state without it, or nil when the
+      # queue is empty.
+      def dequeue
+        return nil if internal_queue.empty?
+
+        [internal_queue.first, with(internal_queue: internal_queue.drop(1).freeze)]
+      end
+
+      # The state with `_event` set to `event`'s value.
+      def put_event(event)
+        variables = Datamodel::SystemVariables
+        with(datamodel: Ractor.make_shareable(variables.put_event(datamodel, variables.of_event(event))))
+      end
+
+      # Whether the state at `index` is active.
+      def active?(index) = configuration.include?(index)
+    end
+
+    # The constructor of a fresh position and its defaults.
+    class MachineState
+      # The round budget when the host sets none.
+      MAX_MACROSTEP_ROUNDS = 10_000
+
+      # The options {fresh} takes, as they stand when the host names none.
+      OPTIONS = {
+        datamodel: {}.freeze, send_types: nil, ioprocessors: {}.freeze, routes: nil, trace: false,
+        max_macrostep_rounds: MAX_MACROSTEP_ROUNDS
+      }.freeze
+
+      # Every field of a position before anything is entered.
+      EMPTY = {
+        configuration: [].freeze, history: {}.freeze, internal_queue: [].freeze, entered_states: [].freeze,
+        states_to_invoke: [].freeze, caller_context: nil, clock: nil, last_selection: nil, running: true,
+        status: :running, macrostep: 0, microstep: 0, round: 0, active_invocations: {}.freeze, invoke_counter: 0
+      }.freeze
+
+      # A fresh position over `machine`: nothing entered, the counters at
+      # zero, and the host's `datamodel` with the system variables over it
+      # (`session_id`, the id the host minted; `send_types`, the types it
+      # registered a processor for, or nil for none; `ioprocessors`, the
+      # `_ioprocessors` entry of each, by type). `routes` are the
+      # {Targets::Routes} the driver declares, or nil; `trace` and
+      # `max_macrostep_rounds` as the fields. The datamodel is copied before
+      # it is frozen, so nothing the host passed is frozen in place.
+      #
+      # @return [MachineState]
+      # @raise [ArgumentError] for an option {OPTIONS} does not name
+      def self.fresh(machine, session_id:, **options)
+        unknown = options.keys - OPTIONS.keys
+        raise ArgumentError, "unknown options: #{unknown.inspect}" unless unknown.empty?
+
+        options = OPTIONS.merge(options)
+        sends = Send::SendState::INITIAL.with(send_types: options[:send_types]&.dup&.freeze, routes: options[:routes])
+        new(machine:, **EMPTY, datamodel: seeded(machine, session_id, options), sends:,
+            **options.slice(:trace, :max_macrostep_rounds))
+      end
+
+      # The starting datamodel, a deeply frozen copy.
+      def self.seeded(machine, session_id, options)
+        seeded = Datamodel::SystemVariables.seed(options[:datamodel], session_id:, name: machine.name,
+                                                                      entries: options[:ioprocessors])
+        Ractor.make_shareable(seeded, copy: true)
+      end
+      private_class_method :seeded
+    end
+  end
+end

data/lib/statifier/interpreter/macrostep.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Interpreter
+    # `mainEventLoop`'s inner loop and the outer body after a selection, as
+    # the reference ports them (`Statifier.Interpreter.microstep/1`,
+    # `macrostep/1` and `main_event_loop/1` in statifier-ex): rounds folded
+    # to a stable configuration, the invoke pass, and the stop.
+    #
+    # Where this departs from the pseudocode, as the reference does:
+    #
+    # - The macrostep is bounded. The pseudocode lets it run forever; here
+    #   the rounds spend a budget ({MachineState}'s `max_macrostep_rounds`,
+    #   `:infinity` for none), and rounds that spend it stop where the last
+    #   one left the state, the chart still running, and answer
+    #   {Effect::BudgetExhausted} last. One budget spans the whole of
+    #   {main_event_loop}, the invoke pass's re-entry included.
+    # - A round is one pass of the inner loop, counted whether or not it
+    #   moves anything, so a position between two rounds is a value.
+    # - A selection's trace carries the microstep the selection ran in,
+    #   before the microstep it starts.
+    #
+    # The invoke pass is {Invoke.invoke_pass}.
+    #
+    # @api private
+    module Macrostep
+      module_function
+
+      # `mainEventLoop`'s outer body after the caller's own selection: the
+      # rounds run; then, while the chart runs, the invoke pass, and the
+      # pseudocode's `continue` when the pass left the internal queue
+      # non-empty, under the budget the rounds left; once the chart has
+      # stopped, `exitInterpreter` ({Stop.exit_interpreter}).
+      #
+      # @return [Stepped]
+      def main_event_loop(state, budget = state.max_macrostep_rounds, effects = [])
+        outcome, state, folded, budget = fold(state, budget)
+        effects += folded
+        return stop(state, effects, outcome) unless state.running
+
+        state, invoked = Invoke.invoke_pass(state)
+        after_invoke_pass(state, effects + invoked, outcome, budget)
+      end
+
+      # After the invoke pass: `continue` (the loop again, under the budget
+      # left) when the pass left the queue non-empty and budget remains;
+      # else the effect that ends the macrostep, {Effect::BudgetExhausted}
+      # when the queue is still non-empty.
+      #
+      # @return [Stepped]
+      def after_invoke_pass(state, effects, outcome, budget)
+        waiting = !state.internal_queue.empty?
+        return main_event_loop(state, budget, effects) if waiting && outcome == :quiescent && !spent?(budget)
+
+        Stepped.new(state:, effects: effects + terminal(state, waiting ? :exhausted : outcome))
+      end
+
+      # The stop after the rounds: the effect that ended them, then
+      # `exitInterpreter`'s.
+      #
+      # @return [Stepped]
+      def stop(state, effects, outcome)
+        exited = Stop.exit_interpreter(state)
+        Stepped.new(state: exited.state, effects: effects + terminal(state, outcome) + exited.effects)
+      end
+
+      # The inner loop on its own, under a fresh budget: the rounds until
+      # the macrostep is stable, the chart stops or the budget is spent,
+      # then the one effect that ends it.
+      #
+      # @return [Stepped]
+      def macrostep(state)
+        outcome, state, effects, = fold(state, state.max_macrostep_rounds)
+        Stepped.new(state:, effects: effects + terminal(state, outcome))
+      end
+
+      # The rounds, each charged against `budget`: `[outcome, state,
+      # effects, budget left]`, `outcome` `:quiescent` (stable, or stopped)
+      # or `:exhausted`. Reaching a stable configuration costs nothing beyond
+      # the rounds already charged.
+      def fold(state, budget)
+        effects = []
+        loop do
+          return [:exhausted, state, effects, budget] if spent?(budget)
+
+          quiescent, stepped = round(state)
+          state = stepped.state
+          effects += stepped.effects
+          return [:quiescent, state, effects, budget] if quiescent
+
+          budget -= 1 unless budget == :infinity
+        end
+      end
+
+      # Whether `budget` (a count of rounds left, or `:infinity`) is spent.
+      def spent?(budget) = budget != :infinity && budget.zero?
+
+      # One pass of the inner `while running and not macrostepDone` loop:
+      # the round counter advances, then the eventless transitions are
+      # taken when any are enabled, else one internal event is taken and
+      # the transitions it enables. `[quiescent, stepped]`: a round that
+      # finds neither, or a chart no longer running, ends the macrostep.
+      def round(state)
+        state = state.begin_round
+        return [true, Stepped.new(state:, effects: [])] unless state.running
+
+        state, transitions, conds = select(state, nil)
+        quiescent, stepped = transitions.empty? ? internal_round(state) : [false, run_selected(state, transitions, nil)]
+        [quiescent, Stepped.new(state: stepped.state, effects: conds + stepped.effects)]
+      end
+
+      # The internal half of a round: the empty eventless selection's trace,
+      # then the oldest queued event set as `_event` and the transitions it
+      # enables taken; an empty queue ends the macrostep.
+      def internal_round(state)
+        event, rest = state.dequeue
+        return [true, run_selected(state, [], nil)] if event.nil?
+
+        dequeued = Blocks.traced(rest, Effect::Trace::EventDequeued, event:, from: :internal)
+        state, transitions, conds = select(rest.put_event(event), event)
+        head = Stepped.new(state:, effects: run_selected(rest, [], nil).effects + dequeued + conds)
+        [false, head.then_step(run_selected(state, transitions, event))]
+      end
+
+      # A selection for `event` (nil for the eventless walk): `[state,
+      # transitions, effects]`, the state with an `error.execution` queued
+      # per condition that failed (origin `{kind: :transition, t_index:}`),
+      # in walk order, and the round's {Effect::Trace::CondsEvaluated} when
+      # it evaluated a written condition.
+      def select(state, event)
+        selected = selection(state, event)
+        failed = selected.evaluations.select { _1.outcome == :error }
+        state = failed.reduce(state) do |acc, one|
+          acc.raise_failure({ kind: :transition, t_index: one.t_index }, one.reason)
+        end
+        [state, selected.transitions, conds_evaluated(state, selected.evaluations)]
+      end
+
+      # The {Selection} walk for `event`, the eventless one for nil.
+      def selection(state, event)
+        return Selection.select_eventless_transitions(state.snapshot, state.datamodel, clock: state.clock) if event.nil?
+
+        Selection.select_transitions(state.snapshot, event.name, state.datamodel, clock: state.clock)
+      end
+
+      # The trace of a round's written conditions, none when it evaluated
+      # none.
+      def conds_evaluated(state, evaluations)
+        return [] if evaluations.empty?
+
+        Blocks.traced(state, Effect::Trace::CondsEvaluated, evaluations: evaluations.map(&:to_h).freeze)
+      end
+
+      # The tail every selection shares: its trace, then, when it took
+      # anything, a new microstep that takes it.
+      #
+      # @return [Stepped]
+      def run_selected(state, transitions, event)
+        selected = Blocks.traced(state, Effect::Trace::TransitionsSelected,
+                                 t_indexes: transitions.map(&:t_index).freeze, event:)
+        return Stepped.new(state:, effects: selected) if transitions.empty?
+
+        Stepped.new(state:, effects: selected).then_step(Step.microstep(state.begin_microstep, transitions))
+      end
+
+      # The one effect that ends a macrostep: {Effect::Trace::MacrostepStable}
+      # when it is stable with the chart running, nothing once it has
+      # stopped, and {Effect::BudgetExhausted} when it spent its budget.
+      def terminal(state, outcome)
+        return exhausted(state) if outcome == :exhausted
+        return [] unless state.running
+
+        Blocks.traced(state, Effect::Trace::MacrostepStable, configuration: state.configuration)
+      end
+
+      # The {Effect::BudgetExhausted} of a macrostep that spent its budget.
+      def exhausted(state)
+        [Frozen.copy(Effect::BudgetExhausted.new(configuration: state.configuration,
+                                                 budget: state.max_macrostep_rounds,
+                                                 pending_internal_events: state.internal_queue,
+                                                 **state.counters))]
+      end
+    end
+  end
+end