statifier 0.0.1 → 0.1.0

data/lib/statifier/driver/routing.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Driver
+    # Where each `<send>` the core answers goes, as the reference's planner
+    # (`Statifier.Session.Effects`) and its session's `deliver/5` route it:
+    # to a host's processor ({Delivery}), onto the external queue, onto the
+    # internal queue through the interpreter's internal delivery, onto a
+    # pending timer, or nowhere, with `error.communication`. Each function answers
+    # `[work, deferred effects]`, or the work alone where nothing is
+    # deferred.
+    #
+    # @api private
+    module Routing
+      module_function
+
+      # An immediate send: handed to its processor, or routed now.
+      def send_now(work, send)
+        return Delivery.hand_off(work, send) if registered?(work, send)
+
+        route(work, send, undelayed: true)
+      end
+
+      # A delayed send: handed to its processor, which holds it, or a
+      # pending timer due its delay from now.
+      def send_later(work, send)
+        return Delivery.hand_off(work, send) if registered?(work, send)
+
+        [schedule(work, send), []]
+      end
+
+      # The work with a pending timer for the delayed send.
+      def schedule(work, send)
+        state = work.state
+        timer = Timer.new(send_id: send.send_id, due_ms: state.now_ms + send.delay_ms, sequence: state.timer_sequence,
+                          delayed: send)
+        work.with_state(timers: (state.timers + [timer]).freeze, timer_sequence: timer.sequence + 1)
+      end
+
+      # Whether the send's type is one the host registered.
+      def registered?(work, send)
+        Interpreter::Targets.classify(work.machine_state.sends.send_types, send.type) == :registered
+      end
+
+      # A `<cancel>`: every pending timer under its id goes, and each
+      # processor holding a delayed send under it is told once.
+      #
+      # @return [Work]
+      def cancel(work, cancel)
+        id = cancel.send_id
+        work = work.with_state(timers: work.state.timers.reject { _1.send_id == id }.freeze)
+        held = work.state.held_sends.fetch(id, nil)
+        return work if held.nil?
+
+        held.each { tell_cancel(work, _1, cancel) }
+        release(work, id)
+      end
+
+      # The work with no processor holding a delayed send under `id`.
+      def release(work, id) = work.with_state(held_sends: work.state.held_sends.except(id).freeze)
+
+      # The processor for `type` told of the `<cancel>`, when it takes one.
+      def tell_cancel(work, type, cancel)
+        processor = work.processors.fetch(type)
+        processor.cancel(cancel, work.context) if processor.respond_to?(:cancel)
+      end
+
+      # A built-in send routed: to the session itself (no target, or its own
+      # `#_scxml_` address) onto the external queue, counted when the send
+      # was undelayed; to `#_internal` onto the internal queue; to
+      # `#_parent` into the parent's mailbox, counted there when undelayed;
+      # to `#_<invokeid>` onto that live child's external queue; anything
+      # else reaches nothing.
+      def route(work, send, undelayed:)
+        event = -> { delivered_event(send, work.state.session_id) }
+        case destination(work, send)
+        when :external then [enqueue(work, event.call, counted: undelayed), []]
+        when :internal then internal(work, send, undelayed)
+        when :parent then [Mailbox.to_parent(work, event.call, counted: undelayed), []]
+        when :invoke then [Mailbox.deliver(work, Interpreter::Targets.parse_target(send.target).id, event.call), []]
+        else communication_error(work, send)
+        end
+      end
+
+      # Where a built-in send's target leads: `:external`, `:internal`,
+      # `:parent` (a session that has one), `:invoke` (a live invocation) or
+      # `:nowhere`.
+      def destination(work, send)
+        route = Interpreter::Targets.parse_target(send.target)
+        work.reaches?(route) ? DESTINATIONS.fetch(route.kind, :nowhere) : :nowhere
+      end
+
+      # Where each kind of target leads when the session reaches it.
+      DESTINATIONS = { self: :external, session: :external, internal: :internal, parent: :parent,
+                       invoke: :invoke }.freeze
+
+      # `event` joined to the external queue, marked as queued by an
+      # undelayed send when `counted`.
+      #
+      # @return [Work]
+      def enqueue(work, event, counted:)
+        event = Frozen.copy(event)
+        work = work.with_state(external_queue: (work.state.external_queue + [event]).freeze)
+        counted ? work.with(counted: (work.counted + [event]).freeze) : work
+      end
+
+      # A send to `#_internal`. An undelayed one is counted against this
+      # call's budget; past it, the event waits on the internal queue unrun
+      # and the session halts.
+      def internal(work, send, undelayed)
+        deliver = ->(acc) { deliver_internal(acc, :internal, name(send), origin(send), fields(send, send.data)) }
+        undelayed ? counted(work, &deliver) : deliver.call(work)
+      end
+
+      # A delivery onto the internal queue counted against this call's
+      # budget with the undelayed sends made there: made by `deliver` within
+      # the budget, and past it made with the chart not run and the session
+      # halted.
+      def counted(work, &deliver)
+        work = work.with(sent_internal: work.sent_internal + 1)
+        work.within?(work.sent_internal) ? deliver.call(work) : past_budget(work, deliver)
+      end
+
+      # An internal delivery past this call's budget: made with the chart
+      # not run, and the session halted, with the budget's effect when it
+      # was not halted already.
+      def past_budget(work, deliver)
+        return [work, []] unless work.machine_state.running
+
+        halted = !work.state.halted.nil?
+        work, = deliver.call(work.with(spent: true))
+        return [work, []] if halted
+
+        [work.with_state(halted: :budget_exhausted), Interpreter::Macrostep.exhausted(work.machine_state)]
+      end
+
+      # A send to something the driver cannot reach: `error.communication`
+      # on the internal queue, carrying the send id the delivered event
+      # would have.
+      def communication_error(work, send, sendid: author_id(send))
+        deliver_internal(work, :platform, "error.communication", origin(send), { data: Predicator::UNDEFINED, sendid: })
+      end
+
+      # The interpreter's internal delivery: the event joins the internal
+      # queue and the chart runs to a stable configuration, its effects
+      # deferred. A stopped chart takes nothing; once the call has halted
+      # the session for its budget, the event waits there unrun.
+      # `fields` are the event's `data:` and `sendid:`.
+      def deliver_internal(work, kind, name, origin, fields)
+        state = work.machine_state
+        return [work, []] unless state.running
+        return [work.with_machine(queued(state, kind, name, origin, fields)), []] if work.spent
+
+        handled = Interpreter::Loop.deliver_internal(work.stamped.machine_state, kind, name, origin, **fields,
+                                                     clock: work.clock)
+        [work.with_machine(handled.state), handled.effects]
+      end
+
+      # The machine state with the event queued and not run.
+      def queued(state, kind, name, origin, fields)
+        state.public_send(kind == :internal ? :raise_internal : :raise_platform, name, origin, **fields)
+      end
+
+      # An event's `data:` and `sendid:` about the send: `data`, and the
+      # send's id when its author named it.
+      def fields(send, data) = { data:, sendid: author_id(send) }
+
+      # The event a delivered send carries, as the reference's
+      # `Statifier.Send.Event.build/3` makes it: from this session's own
+      # address through the SCXML Event I/O Processor, its send id only when
+      # the author named one, and a delayed send's `caller_context`.
+      #
+      # @return [Event]
+      def delivered_event(send, session_id)
+        Event.external(name(send), data: send.data,
+                                   origin: Datamodel::SystemVariables.scxml_location(session_id),
+                                   origintype: Datamodel::SystemVariables::SCXML_EVENT_PROCESSOR,
+                                   sendid: author_id(send),
+                                   caller_context: send.is_a?(Effect::SendDelayed) ? send.caller_context : nil)
+      end
+
+      # The send's event name: the empty name for a send whose event is not
+      # text.
+      def name(send) = send.event.is_a?(String) ? send.event : ""
+
+      # The send's id when its author named it, else nil.
+      def author_id(send) = send.id_from_author? ? send.send_id : nil
+
+      # The cause of an event about the send: its content node.
+      def origin(send) = { kind: :content, c_index: send.c_index, owner: send.owner }
+    end
+  end
+end

data/lib/statifier/driver/session_id.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Driver
+    # The session id the driver mints when the host names none, as the
+    # reference mints one (`Statifier.MachineState.generate_session_id/0`
+    # in statifier-ex): `sess_`, then a 48-bit millisecond timestamp and 80
+    # random bits written in lower-case Crockford base32, so ids sort by the
+    # millisecond they were minted in.
+    #
+    # @api private
+    module SessionId
+      # Crockford base32's alphabet, in symbol order.
+      ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"
+
+      # The timestamp's width in bits.
+      TIME_BITS = 48
+
+      # The random part's width in bytes.
+      RANDOM_BYTES = 10
+
+      module_function
+
+      # A fresh session id.
+      #
+      # @return [String]
+      def mint
+        millis = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) & ((1 << TIME_BITS) - 1)
+        encode((millis << (RANDOM_BYTES * 8)) | Random.urandom(RANDOM_BYTES).unpack1("H*").to_i(16))
+      end
+
+      # The 128 bits of `value` in base32, the last symbol padded with two
+      # zero bits, as an unpadded base32 encoding of 16 bytes writes them.
+      def encode(value)
+        padded = value << 2
+        "sess_#{25.downto(0).map { |digit| ALPHABET[(padded >> (5 * digit)) & 31] }.join}"
+      end
+    end
+  end
+end

data/lib/statifier/driver/work.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Driver
+    # One call's work in progress, a value threaded through the driver's
+    # functions as the interpreter's loop threads its machine state: the
+    # {State} as it stands, the `effects` answered so far, the call's
+    # `processors` and `clock`, and the call's own budget counts: `counted`,
+    # the external events an undelayed send queued for the session in this
+    # call; `taken`, how many of those the call has taken; `sent_internal`,
+    # the undelayed sends it delivered onto its own internal queue; and
+    # `spent`, set once the call has halted the session for its budget; and
+    # `outbox`, what an invoked child's run sent its parent, each a
+    # `[Mail, counted]` pair, `counted` true for an undelayed send's event.
+    # A run of an invoked child is a work of its own, its counts its own.
+    #
+    # @api private
+    Work = ::Data.define(:state, :effects, :processors, :clock, :counted, :taken, :sent_internal, :spent,
+                         :outbox) do
+      # The interpreter's position.
+      def machine_state = state.machine_state
+
+      # The work with the interpreter's position replaced.
+      def with_machine(machine_state) = with(state: state.with(machine_state:))
+
+      # The work with the driver's own fields of the state replaced.
+      def with_state(**fields) = with(state: state.with(**fields))
+
+      # The round budget the chart was started with.
+      def budget = machine_state.max_macrostep_rounds
+
+      # Whether `count` is within the round budget.
+      def within?(count) = budget == :infinity || count <= budget
+
+      # The {Context} a processor is handed.
+      def context = Context.new(session_id: state.session_id)
+
+      # Whether `event` was queued by an undelayed send in this call.
+      def counted?(event) = counted.any? { _1.equal?(event) }
+
+      # What the call answers.
+      def moved = Moved.new(state:, effects: effects.freeze)
+
+      # The work with `effects` answered, in order.
+      def report_all(effects) = with(effects: (self.effects + effects).freeze)
+
+      # The work with `invocation` live under its id.
+      def put_invocation(invocation)
+        with_state(invocations: state.invocations.merge(invocation.invoke_id => invocation).freeze)
+      end
+
+      # The work with the invocation under `invoke_id` no longer live.
+      def drop_invocation(invoke_id) = with_state(invocations: state.invocations.except(invoke_id).freeze)
+
+      # A child's state on this session's clock and timer sequence.
+      def synced(child) = child.with(now_ms: state.now_ms, timer_sequence: state.timer_sequence)
+
+      # The work with the routes its session can reach declared to the core:
+      # its own id, whether it has a parent and its live invocations.
+      def stamped = with_machine(machine_state.with(sends: machine_state.sends.with(routes:)))
+
+      # The {Interpreter::Targets::Routes} the session reaches now.
+      def routes
+        Calls.own_routes(state.session_id, parent: !state.invoked_as.nil?, invokes: state.invocations.keys.sort)
+      end
+
+      # Whether the session reaches `route` (a {Interpreter::Targets::Route})
+      # now: its own `#_scxml_` address, its parent when it has one, and a
+      # live invocation; the targets that need no route are always reached.
+      def reaches?(route)
+        case route.kind
+        when :session then route.id == state.session_id
+        when :parent then !state.invoked_as.nil?
+        when :invoke then state.invocations.key?(route.id)
+        else true
+        end
+      end
+
+      # The work with `mail` sent to the parent.
+      def post(mail, counted: false) = with(outbox: (outbox + [[mail, counted]]).freeze)
+
+      # `effect` as the call reports it: an invoked child's wrapped in an
+      # {Effect::Child} naming the child.
+      def report(effect)
+        state.invoked_as.nil? ? effect : Effect::Child.new(session_id: state.session_id, effect:)
+      end
+    end
+
+    # How a call runs a chart: acting on the effects the core answers, in
+    # order, and taking the external queue one event per macrostep.
+    #
+    # @api private
+    module Run
+      module_function
+
+      # A call's work, before anything ran, over `state`.
+      #
+      # @return [Work]
+      def begin_call(state, processors, clock)
+        Work.new(state:, effects: [].freeze, processors:, clock:, counted: [].freeze, taken: 0, sent_internal: 0,
+                 spent: false, outbox: [].freeze)
+      end
+
+      # Acts on a batch of effects in order. A delivery onto the internal
+      # queue runs the chart at once, but its own effects are acted on after
+      # the batch, as the reference defers them; each is answered as it is
+      # acted on, so what a child it starts or reaches answers follows it. A
+      # child whose batch stops it tells its parent first
+      # ({Mailbox.announce}).
+      #
+      # @return [Work]
+      def perform(work, effects)
+        batch = effects
+        until batch.empty?
+          work = Mailbox.announce(work, batch)
+          work, batch = batch.reduce([work, []]) do |(acc, deferred), effect|
+            acc, more = perform_one(acc.with(effects: (acc.effects + [acc.report(effect)]).freeze), effect)
+            [acc, deferred + more]
+          end
+        end
+        work
+      end
+
+      # One effect acted on: `[work, deferred effects]`.
+      def perform_one(work, effect)
+        case effect
+        when Effect::Send then Routing.send_now(work, effect)
+        when Effect::SendDelayed then Routing.send_later(work, effect)
+        when Effect::Cancel then [Routing.cancel(work, effect), []]
+        when Effect::Done then [stopped(work, effect), []]
+        when Effect::BudgetExhausted then [work.with_state(halted: :budget_exhausted), []]
+        else Invocations.perform(work, effect)
+        end
+      end
+
+      # The chart stopped: the {Effect::Done} is kept, and the pending timers,
+      # the queued external events, the untaken mail and the invocations
+      # its stop left (the completed ones) are discarded. A child that
+      # stopped on its own sends its parent its donedata.
+      def stopped(work, done)
+        Mailbox.return_done(work.with_state(done:, timers: [].freeze, external_queue: [].freeze, mailbox: [].freeze,
+                                            invocations: {}.freeze), done)
+      end
+
+      # Takes the external queue one event per macrostep, while the chart
+      # runs and nothing has halted it, and, once it is empty, the mailbox
+      # one entry at a time ({Mailbox.take_mail}). A counted entry the
+      # session would take past its round budget in this call is left
+      # queued, and the session halts.
+      #
+      # @return [Work]
+      def drain(work)
+        loop do
+          entry, from = next_entry(work)
+          return work if entry.nil?
+
+          work = work.with(taken: work.taken + 1) if work.counted?(entry)
+          return halt(work) unless work.within?(work.taken)
+
+          work = take_entry(work, entry, from)
+        end
+      end
+
+      # The entry the drain takes next and where it waits (`:external` or
+      # `:mailbox`): none once the chart has stopped or a budget has halted
+      # it.
+      def next_entry(work)
+        state = work.state
+        return nil unless state.halted.nil? && work.machine_state.running
+        return [state.external_queue.first, :external] unless state.external_queue.empty?
+
+        [state.mailbox.first, :mailbox] unless state.mailbox.empty?
+      end
+
+      # One entry taken off where it waits.
+      def take_entry(work, entry, from)
+        state = work.state
+        return take(work.with_state(external_queue: state.external_queue.drop(1).freeze), entry) if from == :external
+
+        Mailbox.take_mail(work.with_state(mailbox: state.mailbox.drop(1).freeze), entry)
+      end
+
+      # One external event, one macrostep.
+      def take(work, event)
+        handled = Interpreter::Loop.handle_event(work.machine_state, event, clock: work.clock)
+        return work unless handled.ok?
+
+        perform(work.with_machine(handled.state), handled.effects)
+      end
+
+      # The session halted for this call's round budget, with the effect a
+      # macrostep that spends its rounds answers.
+      def halt(work) = perform(work.with(spent: true), Interpreter::Macrostep.exhausted(work.machine_state))
+    end
+  end
+end

data/lib/statifier/driver.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require_relative "interpreter"
+
+module Statifier
+  # The in-memory driver: the small loop around the interpreter that a host
+  # steps a chart with, as the reference's session is (`Statifier.Session`
+  # and `Statifier.Session.Effects` in statifier-ex), with no process, no
+  # real clock and no I/O. {Statifier.start}, {Statifier.step} and
+  # {Statifier.advance} are its calls; this module holds what they answer
+  # and the work behind them.
+  #
+  # The driver keeps the external queue and the delayed sends as pending
+  # timers on a virtual clock, routes every `<send>` the core answers, and
+  # hands a send of a registered type to the host's processor for that
+  # type. Every call takes a {State} and answers a new one, never changing
+  # the one it was given; nothing is kept between calls but what the
+  # answered state holds.
+  #
+  # Routing, as the reference's planner and session route a send. A send
+  # with no target, or to this session's own `#_scxml_` address, joins the
+  # external queue. A send to `#_internal` is delivered onto the internal
+  # queue through the interpreter's internal delivery
+  # ({Interpreter::Loop.deliver_internal}), and the chart runs to a stable
+  # configuration again; the effects of that run are acted on after the
+  # batch that sent it, as the reference defers them. `#_parent` from an
+  # invoked child, and `#_<invokeid>` naming a live invocation, deliver as
+  # external events (below). Another session's address, a parent a session
+  # does not have and an invocation that is not live reach nothing: the core
+  # refuses such an immediate send itself (the driver declares the routes a
+  # session can reach, its own id, whether it has a parent and the ids of
+  # its live invocations, when it starts, when an event reaches it from
+  # outside, when a timer fires in it and before an internal delivery), a
+  # send the declaration reaches that names nothing live by the time it is
+  # routed fails here, and a delayed one is judged when its timer fires,
+  # each with `error.communication` on the internal queue.
+  #
+  # Invocations, as the reference's session and its built-in `scxml`
+  # handler run them (`Statifier.Session`, `Statifier.Session.Invocations`
+  # and `Statifier.Invoke.Source` in statifier-ex), with one tree of
+  # session states in place of processes. An {Effect::Invoke} of the SCXML
+  # type whose content is markup compiles it, with the namespace relaxed as
+  # inline content is placed, and starts it as a child session, its session
+  # id its parent's, a dot and the invoke id, its datamodel seeded with the
+  # params a root `<data>` of the child names, the rest dropped. A content
+  # that is not markup, or does not compile, and an invocation with no
+  # content (`src` is never fetched) raise `error.communication` and record
+  # nothing; any other type raises `error.execution`. A child is stepped by
+  # this driver on its parent's virtual clock: starting it, an event sent to
+  # it and an autoforwarded event each run it to a stable configuration at
+  # once, and its timers fire with its parent's, in due-then-scheduled order
+  # across the tree. A child inherits its parent's registered send types
+  # (its processors are the call's, handed the child's own session id) and
+  # its trace flag, and every effect its runs answer is among the call's
+  # effects, in the order made, as an {Effect::Child} naming its session id.
+  #
+  # What a child sends its parent - an event to `#_parent`, stamped with the
+  # invoke id; a notice that it reached a top-level final, ahead of the
+  # batch that stops it; and its `done.invoke.<id>` with its donedata -
+  # waits in the parent's mailbox, taken one entry at a time once the
+  # parent's external queue is empty. An entry whose invocation is no longer
+  # live is discarded; the done event retires its invocation once taken. An
+  # {Effect::CancelInvoke} retires the invocation and stops its child,
+  # running its `<onexit>` handlers, unless the child already said it
+  # completed; a cancelled child returns no done event. An
+  # {Effect::Autoforward} delivers the event, unchanged, to a live child.
+  #
+  # The virtual clock. A delayed send of a built-in type becomes a pending
+  # timer due at the clock's time plus its delay. {Statifier.advance} moves
+  # the clock forward and fires every timer due by the new time, earliest
+  # first and, at one due time, in the order they were scheduled; each
+  # fired send is routed then, and a self-addressed one is taken as an
+  # external event before the next timer fires. A `<cancel>` removes every
+  # pending timer under its send id. When the chart stops, its pending
+  # timers and its queued external events are discarded.
+  #
+  # Registered send types. The processors a host registers are passed with
+  # every call, by type, and name the same types for the whole life of a
+  # chart: the types are fixed when the chart starts, as the reference fixes
+  # `_ioprocessors` then. A send of a registered type is handed to its
+  # processor's `deliver` with the event a delivery would carry and a
+  # {Context}, and is never routed or scheduled, delayed or not: the
+  # processor holds a delayed one, and a `<cancel>` of its send id reaches
+  # that processor's `cancel` once. What `deliver` answers is not read,
+  # unless it is a {DeliveryFailure}.
+  #
+  # A failed send. A send a processor could not deliver comes back to the
+  # chart as `error.communication` on its internal queue, its origin the
+  # send's content and its `sendid` the send's id whether or not its author
+  # named it, as the reference's `Statifier.Session.failed_send/3` writes it.
+  # A failure the processor knows of while it is handed the send is answered
+  # from `deliver` as a {DeliveryFailure}, and the event is raised then, at
+  # the send's place in the call, as the reference raises the failure its
+  # processor plans in `deliver/3`. A failure the host learns of later is
+  # reported through {Statifier.report_send_failed}, with the send it was
+  # handed: the driver keeps no table of handed sends. The reason the host
+  # gives is not read, and the chart is not handed it.
+  #
+  # A macrostep that spends its round budget halts the driver as the
+  # reference halts its session: further external events are queued and not
+  # taken. A fired timer to the chart itself joins its external queue and
+  # any other is dropped. One call also spends that budget
+  # twice more, so that it always returns where the reference's session
+  # would keep running: against the events it takes that an undelayed send
+  # queued for the session in this call, and against the undelayed sends it
+  # delivers onto its own internal queue. A fired timer's event is never
+  # counted, and an `:infinity` budget bounds neither.
+  module Driver
+    # A chart's execution between two calls: an immutable value a host keeps
+    # and hands back, reading it only through {Statifier.configuration} and
+    # {Statifier.done?}. Its members are internal and may change in any
+    # release.
+    #
+    # @api private
+    State = ::Data.define(
+      :machine_state, :session_id, :now_ms, :timers, :timer_sequence, :external_queue, :held_sends, :halted,
+      :done, :send_types, :invocations, :mailbox, :invoked_as, :cancelled
+    )
+
+    # A live invocation of a child session, as the parent holds it: its
+    # `invoke_id`; `autoforward`; `completed`, set once the child said it
+    # reached a top-level final; `caller_context`, the {Effect::Invoke}'s,
+    # which its done event carries; and `child`, the child's {State}, whose
+    # `now_ms` and `timer_sequence` are its parent's as they stood when the
+    # child last ran.
+    #
+    # @api private
+    Invocation = ::Data.define(:invoke_id, :autoforward, :completed, :caller_context, :child)
+
+    # What a child sent its parent and the parent has not taken: `kind`
+    # `:completed` (no `payload`), `:event` (the {Event}) or `:done` (the
+    # child's donedata), and the `invoke_id` it came from.
+    #
+    # @api private
+    Mail = ::Data.define(:kind, :invoke_id, :payload)
+
+    # A delayed send waiting on the virtual clock: its send id, the virtual
+    # time it is due at, the order it was scheduled in, and the
+    # {Effect::SendDelayed} itself, `delayed`.
+    #
+    # @api private
+    Timer = ::Data.define(:send_id, :due_ms, :sequence, :delayed)
+
+    # What a call that moves a chart answers as its result's `value`.
+    #
+    # @!attribute [r] state
+    #   @return [State] the chart's execution after the call
+    # @!attribute [r] effects
+    #   @return [Array] every effect the call's runs answered, in the order
+    #     they were made, a frozen list of {Statifier::Effect} values, an
+    #     invoked child's each wrapped in an {Effect::Child}
+    Moved = ::Data.define(:state, :effects)
+
+    # What {Statifier.done?} answers as its result's `value`.
+    #
+    # @!attribute [r] done
+    #   @return [Boolean] whether the chart has stopped
+    # @!attribute [r] donedata
+    #   @return [Object, nil] the top-level final's `<donedata>` as the
+    #     {Effect::Done} carried it (`Predicator::UNDEFINED` when it has
+    #     none); nil while the chart runs
+    # @!attribute [r] configuration
+    #   @return [Array<String>, nil] the states active when the chart
+    #     stopped, named as {Statifier.configuration} names them; nil while
+    #     the chart runs
+    DoneStatus = ::Data.define(:done, :donedata, :configuration) do
+      # @return [Boolean] whether the chart has stopped
+      def done? = done
+    end
+
+    # What the driver tells a processor about the session it is called
+    # for.
+    #
+    # @!attribute [r] session_id
+    #   @return [String] the session's id, the one `_sessionid` reads
+    Context = ::Data.define(:session_id)
+
+    # What a processor's `deliver` answers for a send it could not deliver:
+    # the send then fails within the call that handed it, as
+    # {Statifier.report_send_failed} fails a send reported later.
+    #
+    # @!attribute [r] reason
+    #   @return [Object, nil] the host's own account of the failure; the
+    #     driver does not read it and the chart is not handed it
+    DeliveryFailure = ::Data.define(:reason) do
+      # A failure with no reason given.
+      def initialize(reason: nil) = super
+    end
+
+    # The round budget when the host sets none.
+    MAX_MACROSTEP_ROUNDS = Interpreter::MachineState::MAX_MACROSTEP_ROUNDS
+
+    require_relative "driver/session_id"
+    require_relative "driver/work"
+    require_relative "driver/routing"
+    require_relative "driver/delivery"
+    require_relative "driver/checks"
+    require_relative "driver/invocations"
+    require_relative "driver/mailbox"
+    require_relative "driver/calls"
+
+    private_constant :Calls, :Checks, :Delivery, :Invocation, :Invocations, :Mail, :Mailbox, :MAX_MACROSTEP_ROUNDS,
+                     :Routing, :Run, :SessionId, :State, :Timer, :Work
+  end
+end