statifier 0.0.1 → 0.1.0

data/lib/statifier/lowering/placement.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Lowering
+    # Placing a container's lowered children into its fields. A builder
+    # answers its node tagged with the kind of place it goes in (`:state` for
+    # the four state kinds, `:content_node` for executable content, the
+    # element's own name for the rest); a container names the tags it has a
+    # place for, and every other child is misplaced. Placement never looks at
+    # the parent's element name except to word that error.
+    #
+    # @api private
+    module Placement
+      # The element name a misplaced executable node is reported under.
+      NAMES = {
+        Document::Raise => "raise", Document::Log => "log", Document::Assign => "assign",
+        Document::If => "if", Document::Foreach => "foreach", Document::Script => "script",
+        Document::Send => "send", Document::Cancel => "cancel"
+      }.freeze
+
+      # The places of a container whose one place is executable content.
+      CONTENT = { content_node: %i[content many] }.freeze
+
+      module_function
+
+      # Folds `results` (the tagged children, nil for one that could not be
+      # made) into the places `slots` names, `{tag => [field, :many | :one]}`;
+      # a node class as a key places executable content of that class alone.
+      # A `:many` field collects in document order, a `:one` field keeps the
+      # last. Answers the filled fields and the misplaced errors, newest
+      # first, as the reference accumulates them.
+      def fold(results, slots, parent_name)
+        filled = {}
+        errors = []
+        results.each do |result|
+          next if result.nil?
+
+          field, arity = slot_for(slots, *result)
+          next errors.unshift(misplaced(*result, parent_name)) if field.nil?
+
+          arity == :many ? (filled[field] ||= []) << result.last : filled[field] = result.last
+        end
+        [filled, errors]
+      end
+
+      # A `:many` field's nodes, frozen.
+      def many(filled, field) = (filled[field] || Reading::EMPTY).freeze
+
+      # The field and arity `slots` names for a tagged node, or nil.
+      def slot_for(slots, tag, node)
+        slots.fetch(tag) { tag == :content_node ? slots[node.class] : nil }
+      end
+
+      # The misplaced error for a tagged node its parent has no place for.
+      def misplaced(tag, node, parent_name)
+        return Errors.misplaced(NAMES.fetch(node.class), parent_name, span(node)) if tag == :content_node
+
+        Errors.misplaced(tag.to_s, parent_name, node.location)
+      end
+
+      # An assign's `location` is its attribute; its span is `node_location`.
+      def span(node) = node.is_a?(Document::Assign) ? node.node_location : node.location
+    end
+  end
+end

data/lib/statifier/lowering/reading.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Lowering
+    # Reading an element's attributes and text as the builders need them.
+    #
+    # @api private
+    module Reading
+      # What a list attribute splits on: Unicode white space except the
+      # no-break spaces, as the reference splits it.
+      SPLIT = /[\t\n\v\f\r \u0085\u1680\u2000-\u2006\u2008-\u200a\u2028\u2029\u205f\u3000]+/
+      BLANK = /\A[#{Errors::TRIM}]*\z/
+      EMPTY = [].freeze
+      NO_LOCATIONS = {}.freeze
+
+      module_function
+
+      # The value of the first attribute written with `name`, or nil.
+      def value(element, name) = attribute(element, name)&.value
+
+      # An attribute split on white space: absent and empty both answer an
+      # empty list, told apart by the attribute's location.
+      def list(element, name)
+        raw = value(element, name)
+        raw.nil? ? EMPTY : raw.split(SPLIT).reject(&:empty?).map(&:freeze).freeze
+      end
+
+      # An attribute mapped through `mapping`, or `default` when it is absent
+      # or not a key of `mapping`.
+      def choice(element, name, mapping, default) = mapping.fetch(value(element, name), default)
+
+      # The value spans of the named attributes that were written, keyed by
+      # name as a Symbol.
+      def locations(element, names)
+        names.each_with_object({}) do |name, spans|
+          found = attribute(element, name)
+          spans[name.to_sym] = found.value_location if found&.value_location
+        end.freeze
+      end
+
+      # The element's own character data, its text children joined.
+      def text(element)
+        element.children.grep(XML::Text).map(&:value).join.freeze
+      end
+
+      # Whether trimming Unicode white space from `text` leaves nothing.
+      def blank?(text) = BLANK.match?(text)
+
+      # The first attribute written with `name`, or nil.
+      def attribute(element, name) = element.attributes.find { |candidate| candidate.name == name }
+    end
+  end
+end

data/lib/statifier/lowering/states.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Lowering
+    # The builders of `<scxml>`, the state family, `<initial>`,
+    # `<transition>` and the blocks. Each takes an element and the source,
+    # and answers its node tagged with its place (the root's untagged) and
+    # its errors.
+    #
+    # @api private
+    module States
+      ROOT_SLOTS = {
+        state: %i[states many], datamodel: %i[datamodel_element one], Document::Script => %i[scripts many]
+      }.freeze
+      STATE_SLOTS = {
+        state: %i[states many], transition: %i[transitions many], initial: %i[initial_element one],
+        onentry: %i[onentry many], onexit: %i[onexit many], donedata: %i[donedata one],
+        datamodel: %i[datamodel_element one], invoke: %i[invoke many]
+      }.freeze
+      INITIAL_SLOTS = { transition: %i[transitions many] }.freeze
+      ROOT_ATTRIBUTES = %w[initial name datamodel binding version xmlns].freeze
+      BINDINGS = { "early" => :early, "late" => :late }.freeze
+      HISTORY_TYPES = { "shallow" => :shallow, "deep" => :deep }.freeze
+      TRANSITION_TYPES = { "internal" => :internal, "external" => :external }.freeze
+
+      module_function
+
+      # `<scxml>`: answers the {Document} and its errors.
+      def scxml(element, source)
+        filled, errors = lower_children(element, source, ROOT_SLOTS)
+        document = Document.new(
+          location: element.location, **%i[name version xmlns datamodel].to_h { [_1, Reading.value(element, _1.to_s)] },
+          namespace: element.namespace, binding: Reading.choice(element, "binding", BINDINGS, :early),
+          initial: Reading.list(element, "initial"), states: Placement.many(filled, :states),
+          datamodel_element: filled[:datamodel_element], scripts: Placement.many(filled, :scripts),
+          attribute_locations: Reading.locations(element, ROOT_ATTRIBUTES)
+        )
+        [document, errors]
+      end
+
+      # The four state kinds share one builder; each answers a
+      # {Document::State} tagged `:state`.
+      def state(element, source) = state_like(element, source, :state)
+      def parallel(element, source) = state_like(element, source, :parallel)
+      def final(element, source) = state_like(element, source, :final)
+
+      # A history's `type` lowers to `:shallow` when it is neither value, and
+      # its location is kept so that a check can point at it.
+      def history(element, source)
+        (tag, state), errors = state_like(element, source, :history)
+        locations = state.attribute_locations.merge(Reading.locations(element, %w[type])).freeze
+        history_type = Reading.choice(element, "type", HISTORY_TYPES, :shallow)
+        [[tag, state.with(history_type:, attribute_locations: locations)], errors]
+      end
+
+      # An `<initial>`: every `<transition>` child it holds.
+      def initial(element, source)
+        filled, errors = lower_children(element, source, INITIAL_SLOTS)
+        [[:initial, Document::Initial.new(location: element.location,
+                                          transitions: Placement.many(filled, :transitions))], errors]
+      end
+
+      # A `<transition>`: its attributes and its executable content.
+      def transition(element, source)
+        filled, errors = lower_children(element, source, Placement::CONTENT)
+        node = Document::Transition.new(
+          location: element.location, event: Reading.list(element, "event"),
+          target: Reading.list(element, "target"), cond: Reading.value(element, "cond"),
+          type: Reading.choice(element, "type", TRANSITION_TYPES, :external),
+          content: Placement.many(filled, :content),
+          attribute_locations: Reading.locations(element, %w[event target cond type])
+        )
+        [[:transition, node], errors]
+      end
+
+      # `<onentry>`, `<onexit>` and `<finalize>` each answer one block,
+      # tagged with the element's name.
+      def onentry(element, source) = block(element, source, :onentry)
+      def onexit(element, source) = block(element, source, :onexit)
+      def finalize(element, source) = block(element, source, :finalize)
+
+      # One {Document::Block} per element, never flattened.
+      def block(element, source, tag)
+        filled, errors = lower_children(element, source, Placement::CONTENT)
+        [[tag, Document::Block.new(location: element.location, content: Placement.many(filled, :content))], errors]
+      end
+
+      # A state of `kind`: its attributes and its children in their fields.
+      def state_like(element, source, kind)
+        filled, errors = lower_children(element, source, STATE_SLOTS)
+        node = Document::State.new(
+          kind:, location: element.location, id: Reading.value(element, "id"),
+          initial: Reading.list(element, "initial"), initial_element: filled[:initial_element],
+          states: Placement.many(filled, :states), transitions: Placement.many(filled, :transitions),
+          onentry: Placement.many(filled, :onentry), onexit: Placement.many(filled, :onexit),
+          history_type: nil, donedata: filled[:donedata], datamodel_element: filled[:datamodel_element],
+          invoke: Placement.many(filled, :invoke), attribute_locations: Reading.locations(element, %w[id initial])
+        )
+        [[:state, node], errors]
+      end
+
+      # Walks an element's children and places them: answers the filled
+      # fields and the walk's errors followed by the misplaced ones.
+      def lower_children(element, source, slots)
+        results, errors = Lowering.walk_children(element, source)
+        filled, misplaced = Placement.fold(results, slots, element.name)
+        [filled, errors + misplaced]
+      end
+    end
+  end
+end

data/lib/statifier/lowering.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "document"
+require_relative "lowering/error"
+require_relative "lowering/reading"
+require_relative "lowering/placement"
+require_relative "lowering/states"
+require_relative "lowering/executable"
+require_relative "lowering/data"
+
+module Statifier
+  # The reader's element tree in, the typed chart ({Document}) out: the
+  # second step of reading a chart, a port of the reference's lowering.
+  #
+  # One walk. Each element is lowered by the builder its local name selects;
+  # a builder lowers its children first, then places each into a field of
+  # its own node, and a child its node has no place for is misplaced. An
+  # element is SCXML's own when its name resolves to the SCXML namespace or
+  # to none, so a chart that declares no namespace lowers as its declared
+  # twin does; reporting a missing declaration is a later check's.
+  # `<content>`, `<assign>`, `<data>` and `<script>` hold text as their
+  # payload and are exempt from the stray-text rule; the element children of
+  # `<content>` and `<assign>` are kept as a slice of the source, never
+  # lowered.
+  #
+  # The walk does not stop at the first refusal: it collects every one, and
+  # the chart is answered only when there are none, never a partial one.
+  #
+  # @api private
+  module Lowering
+    # The SCXML namespace.
+    SCXML_NAMESPACE = "http://www.w3.org/2005/07/scxml"
+
+    # The builder of each element that may appear below the root. `<scxml>`
+    # is not one: it is only ever the root.
+    BUILDERS = {
+      "state" => [States, :state], "parallel" => [States, :parallel], "final" => [States, :final],
+      "history" => [States, :history], "initial" => [States, :initial], "transition" => [States, :transition],
+      "onentry" => [States, :onentry], "onexit" => [States, :onexit], "finalize" => [States, :finalize],
+      "raise" => [Executable, :raise_node], "log" => [Executable, :log], "assign" => [Executable, :assign],
+      "if" => [Executable, :if_node], "elseif" => [Executable, :elseif], "else" => [Executable, :else_node],
+      "foreach" => [Executable, :foreach], "script" => [Executable, :script], "send" => [Executable, :send_node],
+      "cancel" => [Executable, :cancel], "datamodel" => [DataModel, :datamodel], "data" => [DataModel, :data],
+      "donedata" => [DataModel, :donedata], "param" => [DataModel, :param], "content" => [DataModel, :content],
+      "invoke" => [DataModel, :invoke]
+    }.freeze
+
+    # The encodings whose strings the reader reads from their bytes.
+    READ_AS_BYTES = [Encoding::BINARY, Encoding::US_ASCII].freeze
+
+    # What {Lowering.lower} answers: the chart as `value`, or every refusal,
+    # in document order, as `errors`.
+    Result = ::Data.define(:value, :errors) do
+      # @return [Boolean] true when the tree lowered
+      def ok? = errors.empty?
+    end
+
+    # Lowers a parsed `<scxml>` element tree into its typed chart.
+    #
+    # @param root [XML::Element] the root element {XML.parse} answered
+    # @param source [String] the document it was parsed from; `<content>` and
+    #   `<assign>` slice their markup out of it
+    # @return [Result] the {Document} as `value`, or the {Error}s as `errors`
+    def self.lower(root, source)
+      refusal = root_refusal(root)
+      return refuse([refusal]) if refusal
+
+      document, errors = States.scxml(root, utf8(source))
+      errors.empty? ? Result.new(value: document, errors: Reading::EMPTY) : refuse(errors)
+    end
+
+    # Why a root does not lower: it is foreign, or it is not `<scxml>`.
+    def self.root_refusal(root)
+      return Errors.foreign_element(root.name, root.namespace, root.location) unless scxml?(root.namespace)
+
+      name = local_name(root.name)
+      Errors.unexpected_root(name, root.location) unless name == "scxml"
+    end
+
+    # Lowers an element's children: each child element by its builder, each
+    # text run checked against the stray-text rule. Answers the tagged
+    # results in document order (nil for an element that made no node) and
+    # the errors newest first, as the reference accumulates them.
+    def self.walk_children(element, source)
+      element.children.each_with_object([[], []]) do |child, (results, errors)|
+        result, child_errors = child.is_a?(XML::Text) ? [nil, walk_text(child)] : walk_element(child, source)
+        results << result
+        errors.unshift(*child_errors.reverse)
+      end
+    end
+
+    def self.walk_text(text)
+      Reading.blank?(text.value) ? Reading::EMPTY : [Errors.stray_text(text.value, text.location)]
+    end
+
+    # A child element lowered by its builder, or refused when it is foreign
+    # or no builder reads it.
+    def self.walk_element(element, source)
+      return [nil, [Errors.foreign_element(element.name, element.namespace, element.location)]] \
+        unless scxml?(element.namespace)
+
+      builder, method = BUILDERS[local_name(element.name)]
+      return [nil, [Errors.unsupported(element.name, element.location)]] if builder.nil?
+
+      builder.public_send(method, element, source)
+    end
+
+    def self.scxml?(uri) = uri.nil? || uri == SCXML_NAMESPACE
+
+    def self.local_name(name) = name.split(":", 2).last
+
+    # Every error in document order: by start offset, found order kept at
+    # one offset.
+    def self.refuse(errors)
+      sorted = errors.each_with_index.sort_by { |error, index| [error.location.start_offset, index] }.map(&:first)
+      Result.new(value: nil, errors: sorted.freeze)
+    end
+
+    # The source as the reader read it, so that its byte offsets slice it.
+    def self.utf8(source)
+      return source if source.encoding == Encoding::UTF_8
+      return source.dup.force_encoding(Encoding::UTF_8) if READ_AS_BYTES.include?(source.encoding)
+
+      source.encode(Encoding::UTF_8)
+    end
+
+    private_class_method :root_refusal, :walk_text, :walk_element, :scxml?, :local_name, :refuse, :utf8
+  end
+end

data/lib/statifier/machine/content.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Statifier
+  class Machine
+    # The compiled executable content. Every node carries its `c_index`, its
+    # place in one dense index space over the whole chart in document order
+    # (a container before its children), the index an execution error names.
+    # An expression is a {Compiled} or a {Static}; one whose failure is
+    # deferred to when it runs is an {Invalid}.
+
+    # A `<raise>`: `event` as written.
+    #
+    # @api private
+    Raise = ::Data.define(:c_index, :event, :location)
+
+    # A `<log>`: `label` as written, `expr` a {Compiled} or nil, and
+    # `expr_location` where it was written, nil when it was not.
+    #
+    # @api private
+    Log = ::Data.define(:c_index, :label, :expr, :location, :expr_location)
+
+    # An `<assign>`. `location` is the path assigned to, as written, and
+    # `location_location` its span; `node_location` is the element's span.
+    # `value` is its `expr` (a {Compiled}, or an {Invalid} when it did not
+    # compile), else its markup children as a {Static} string, else its text
+    # folded to a {Static} value; `expr_location` is where `expr` was
+    # written, nil when it was not.
+    #
+    # @api private
+    Assign = ::Data.define(:c_index, :location, :node_location, :value, :location_location, :expr_location)
+
+    # An `<if>`: one {Branch} for the `<if>` and one per `<elseif>` and
+    # `<else>`.
+    #
+    # @api private
+    If = ::Data.define(:c_index, :location, :branches)
+
+    class If
+      # One branch: `cond` a {Compiled}, nil for an `<else>`, with
+      # `cond_location`; `content` the content up to the next branch.
+      #
+      # @api private
+      Branch = ::Data.define(:cond, :cond_location, :content)
+    end
+
+    # A `<foreach>`: `array` a {Compiled}, `item` and `index` as written
+    # (`index` nil when absent), each with the span of its attribute
+    # (`index_location` nil when `index` is), and its content.
+    #
+    # @api private
+    Foreach = ::Data.define(
+      :c_index, :location, :array, :array_location, :item, :item_location, :index, :index_location, :content
+    )
+
+    # A `<script>`: `program` a {Program}, or an {Invalid} when its body did
+    # not compile; `node_location` the element's span.
+    #
+    # @api private
+    Script = ::Data.define(:c_index, :program, :node_location)
+
+    # A `<send>`. `event`, `target`, `type` and `delay` each fold a literal
+    # attribute and its `expr` twin into one expression: a {Static} for the
+    # literal, a {Compiled} for the twin, nil when neither was written.
+    # `id` and `idlocation` are as written; `namelist` holds a {Param} per
+    # entry (a location read by its own name, an {Invalid} when it did not
+    # compile), `params` a {Param} per `<param>`, and `content` the
+    # `<content>` child's value, or nil.
+    #
+    # @api private
+    Send = ::Data.define(
+      :c_index, :location, :event, :target, :type, :id, :idlocation, :delay, :namelist, :params, :content,
+      :attribute_locations
+    )
+
+    # A `<cancel>`: `sendid` a {Static} for the literal attribute, else a
+    # {Compiled} for `sendidexpr`.
+    #
+    # @api private
+    Cancel = ::Data.define(:c_index, :location, :sendid, :attribute_locations)
+  end
+end

data/lib/statifier/machine/data.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Statifier
+  class Machine
+    # A compiled `<data>`. `value` is, in the specification's precedence, its
+    # `expr` (a {Compiled}, or an {Invalid} when it did not compile, which
+    # fails when the datamodel binds it), its `src` (a {Src}), its text
+    # folded to a {Static} value, or a {Static} nil. `value_location` is
+    # where the value was written: the attribute when one was, else the
+    # element.
+    #
+    # @api private
+    Data = ::Data.define(:d_index, :id, :value, :location, :value_location)
+
+    # A compiled `<param>`, or one `namelist` entry. `kind` is `:expr` when
+    # the value is an `expr` and `:location` when it is a location read;
+    # `expr` is a {Compiled} (a `namelist` entry's an {Invalid} when it did
+    # not compile); `expr_location` is where it was written.
+    #
+    # @api private
+    Param = ::Data.define(:name, :kind, :expr, :expr_location, :location)
+
+    # A final state's compiled `<donedata>`: its `<content>`'s value as
+    # `expr` with `expr_location`, or its {Param}s.
+    #
+    # @api private
+    Donedata = ::Data.define(:location, :expr, :expr_location, :params)
+
+    # A compiled `<invoke>`. `index` is its position among its state's
+    # `<invoke>` elements; `type` and `src` fold a literal attribute and its
+    # `expr` twin as a `<send>`'s do; `id` and `idlocation` are as written;
+    # `namelist` and `params` hold {Param}s, as a `<send>`'s do; `content` is
+    # the `<content>` child's value or nil; `finalize` its {Block}, or nil
+    # when none was written.
+    #
+    # @api private
+    Invoke = ::Data.define(
+      :index, :location, :type, :src, :id, :idlocation, :namelist, :params, :content, :autoforward,
+      :finalize, :attribute_locations
+    )
+  end
+end

data/lib/statifier/machine/states.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Statifier
+  class Machine
+    # A compiled state. The root at index 0 has the kind `:scxml`, no id and
+    # no parent; every other kind is the document's (`:state`, `:parallel`,
+    # `:final`, `:history`).
+    #
+    # - `parent`: the parent's index, nil only for the root;
+    # - `last`: the highest index in the state's subtree, so its
+    #   descendants are `index + 1` to `last`;
+    # - `children`: the direct children's indexes in document order, history
+    #   states included, and `history_children` those that are histories;
+    # - `initial`: the states a default entry enters, by the specification's
+    #   precedence (the `initial` attribute, else the `<initial>` element's
+    #   one transition's targets, else the first child); empty for every
+    #   kind but a `<state>` and the root;
+    # - `history_type`: `:shallow` or `:deep` on a history, nil otherwise;
+    # - `transitions`: the selectable transitions' `t_index`es in document
+    #   order, empty for a history;
+    # - `initial_transition`: the `t_index` of the `<initial>` element's
+    #   transition, and `history_default` that of a history's default, each
+    #   nil when absent;
+    # - `onentry` and `onexit`: one {Block} per element;
+    # - `donedata`: a final state's {Donedata}, or nil;
+    # - `data`: the `d_index`es of the `<data>` its own `<datamodel>`
+    #   declares;
+    # - `invoke`: its {Invoke}s in document order.
+    #
+    # @api private
+    State = ::Data.define(
+      :index, :id, :kind, :parent, :last, :children, :initial, :history_type, :history_children,
+      :transitions, :onentry, :onexit, :initial_transition, :history_default, :donedata, :data,
+      :invoke, :location, :attribute_locations
+    )
+
+    # A compiled transition. `source` is the index of the state that holds
+    # it; `targets` the target states' indexes; `events` each event
+    # descriptor split on its dots (`a.b c` is `[["a", "b"], ["c"]]`); `cond`
+    # the {Compiled} condition, or nil when none was written, and
+    # `cond_location` where it was written, nil exactly when `cond` is;
+    # `type` `:external` or `:internal`; `content` its executable content.
+    #
+    # @api private
+    Transition = ::Data.define(
+      :t_index, :source, :targets, :events, :cond, :type, :content, :location, :cond_location,
+      :attribute_locations
+    )
+
+    # One `<onentry>`, `<onexit>` or `<finalize>` block: its executable
+    # content.
+    #
+    # @api private
+    Block = ::Data.define(:location, :content)
+  end
+end

data/lib/statifier/machine/values.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Statifier
+  class Machine
+    # An expression compiled by `Predicator.compile`: its `instructions`, the
+    # list predicator evaluates, and its `source`, as written.
+    #
+    # @api private
+    Compiled = ::Data.define(:instructions, :source)
+
+    # A statement program (a `<script>` body) compiled by
+    # `Predicator.compile_program`: its `instructions`, the list predicator
+    # executes, and its `source`, as written.
+    #
+    # @api private
+    Program = ::Data.define(:instructions, :source)
+
+    # A value fixed when the chart compiled, with nothing to evaluate: a
+    # literal attribute, a `<content>` body, or an in-line `<data>` or
+    # `<assign>` value.
+    #
+    # @api private
+    Static = ::Data.define(:value)
+
+    # An expression or program that did not compile, where the failure is
+    # deferred to when it runs: `error` is the {Compiler::Error} the compile
+    # answered.
+    #
+    # @api private
+    Invalid = ::Data.define(:error)
+
+    # A `<data>` value the host resolves: `src` as written.
+    #
+    # @api private
+    Src = ::Data.define(:src)
+  end
+end

data/lib/statifier/machine.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Statifier
+  # The compiled chart the interpreter steps: what {Compiler.compile} makes of
+  # a validated {Document}, and the `value` of a successful {Statifier.compile}.
+  # It is a frozen value, deeply: every node, list and compiled expression in
+  # it is frozen, so it may be shared between executions and Ractors.
+  #
+  # Every state is interned to an index in document order. Index 0 is the
+  # `<scxml>` root, made from the document's own fields: the specification
+  # treats `<scxml>` as a state when it computes a transition's domain, and
+  # giving it an index removes the special case. A state's descendants are
+  # exactly the indexes after its own up to and including its `last`, so
+  # ancestry and document order are integer comparisons.
+  #
+  # Transitions and `<data>` elements have their own dense index spaces,
+  # `t_index` and `d_index`, assigned in document order. Executable content
+  # carries its `c_index` on each node and sits inline in the block,
+  # transition, branch or loop body that holds it.
+  #
+  # The fields: `states`, every {State} by index; `id_to_index`, the index of
+  # every state written with a non-empty id; `transitions`, every
+  # {Transition} by `t_index`; `data_elements`, every {Data} by `d_index`,
+  # the root's own first; `global_scripts`, the `<script>` children of
+  # `<scxml>` (each a {Program} or an {Invalid}), run once when the chart
+  # starts; `name`, `datamodel` and `binding`, the root's attributes;
+  # `location`, the root's span; and `warnings`, the
+  # {Validator::Warning}s the chart was compiled with.
+  #
+  # Its shape is internal and may change in any release: a host passes a
+  # machine on and reads one of its members only, `warnings`, the documented
+  # exception ({Statifier.compile} says what it holds). Every other member
+  # is private.
+  #
+  # @api private
+  Machine = ::Data.define(
+    :states, :id_to_index, :transitions, :data_elements, :global_scripts,
+    :name, :datamodel, :binding, :location, :warnings
+  ) do
+    # @return [State] the state at `index`
+    # @raise [IndexError] when the machine holds no such state
+    def state(index) = states.fetch(index)
+
+    # Whether `descendant` sits inside `ancestor`. Proper: a state is not its
+    # own descendant.
+    def descendant?(descendant, ancestor) = ancestor < descendant && descendant <= state(ancestor).last
+
+    # Whether the state has no child states. A final state is atomic.
+    def atomic?(index) = state(index).children.empty?
+
+    # Whether the state is compound: a `<state>` or the root with at least
+    # one child. A parallel is never compound.
+    def compound?(index)
+      node = state(index)
+      %i[state scxml].include?(node.kind) && !node.children.empty?
+    end
+
+    # Whether the state is a `<parallel>`.
+    def parallel?(index) = state(index).kind == :parallel
+
+    # Whether the state is a `<final>`.
+    def final?(index) = state(index).kind == :final
+
+    # Whether the state is a `<history>` pseudo-state.
+    def history?(index) = state(index).kind == :history
+
+    # The state's child states in document order, history pseudo-states left
+    # out (the specification's `getChildStates`).
+    def child_states(index)
+      node = state(index)
+      node.children - node.history_children
+    end
+
+    # The state's proper ancestors, nearest first and the root last (the
+    # specification's `getProperAncestors` with no bound).
+    def proper_ancestors(index)
+      ancestors = []
+      parent = state(index).parent
+      until parent.nil?
+        ancestors << parent
+        parent = state(parent).parent
+      end
+      ancestors
+    end
+
+    # The least common compound ancestor of `indexes` (the specification's
+    # `findLCCA`): the nearest proper ancestor of the first index that is
+    # compound and holds every index as a descendant, or nil when none does.
+    # A parallel never qualifies.
+    def lcca(indexes)
+      return nil if indexes.empty?
+
+      proper_ancestors(indexes.first).find do |candidate|
+        compound?(candidate) && indexes.all? { descendant?(_1, candidate) }
+      end
+    end
+  end
+end
+
+require_relative "machine/values"
+require_relative "machine/states"
+require_relative "machine/content"
+require_relative "machine/data"