statifier 0.0.1 → 0.1.0

data/lib/statifier/position/rebuild.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Position
+    # A driver state rebuilt from a checked position, as the reference's
+    # `import/2` rebuilds its machine state: every id resolved to its index,
+    # the root re-added, the internal queue empty, and the fields a driver
+    # declares (the send types and the routes) stamped afresh.
+    #
+    # @api private
+    module Rebuild
+      module_function
+
+      # The driver state over `machine` the position holds, `datamodel` its
+      # decoded variables and `types` the registered send types.
+      #
+      # @return [Driver::State]
+      def state(machine, position, datamodel, types)
+        session_id = datamodel[SESSION_ID]
+        machine_state = machine_state(machine, position, datamodel, types, session_id)
+        DRIVER_STATE.new(machine_state:, session_id:, now_ms: 0, timers: [].freeze, timer_sequence: 0,
+                         external_queue: [].freeze, held_sends: {}.freeze, halted: nil, done: done(machine_state),
+                         send_types: types, invocations: {}.freeze, mailbox: [].freeze, invoked_as: nil,
+                         cancelled: false)
+      end
+
+      # The interpreter's position. The root is active whenever any state
+      # is, and has been entered whenever any state has.
+      def machine_state(machine, position, datamodel, types, session_id)
+        configuration = indexes(machine, position["configuration"])
+        Interpreter::MachineState.new(
+          machine:, configuration: rooted(configuration), history: history(machine, position["history_values"]),
+          datamodel:, internal_queue: [].freeze, entered_states: rooted(indexes(machine, position["entered_states"])),
+          states_to_invoke: indexes(machine, position["states_to_invoke"]), sends: sends(position, types, session_id),
+          caller_context: nil, clock: nil, last_selection: nil, **fields(position),
+          active_invocations: invocations(machine, position["active_invocations"])
+        )
+      end
+
+      # The indexes of the states `ids` name, ascending, frozen.
+      def indexes(machine, ids) = ids.map { machine.id_to_index.fetch(_1) }.uniq.sort.freeze
+
+      # `indexes` with the root, when they hold any state.
+      def rooted(indexes) = indexes.empty? ? indexes : ([0] | indexes).sort.freeze
+
+      # The recorded history by index.
+      def history(machine, values)
+        values.to_h { |key, ids| [machine.id_to_index.fetch(key), indexes(machine, ids)] }.freeze
+      end
+
+      # The live invocations by state index and invoke index.
+      def invocations(machine, entries)
+        entries.to_h { [[machine.id_to_index.fetch(_1["state"]), _1["invoke_index"]].freeze, -_1["invoke_id"]] }.freeze
+      end
+
+      # The send state: the position's two sequences, and the types and
+      # routes a driver declares as a chart starts.
+      def sends(position, types, session_id)
+        Interpreter::Send::SendState.new(
+          send_counter: position["send_counter"], timer_counter: position["timer_counter"],
+          send_types: (types unless types.empty?), routes: DRIVER_CALLS.own_routes(session_id)
+        )
+      end
+
+      # The scalar fields, as the machine state holds them.
+      def fields(position)
+        budget = position["max_macrostep_rounds"]
+        { running: position["running"], status: position["status"].to_sym, macrostep: position["macrostep"],
+          microstep: position["microstep"], round: position["round"], trace: position["trace"],
+          max_macrostep_rounds: budget == "infinity" ? :infinity : budget, invoke_counter: position["invoke_counter"] }
+      end
+
+      # The driver's record of a stopped chart: a stopped position carries
+      # no donedata (the reference's carries it only in the done effect), so
+      # it is undefined, and the configuration is the position's own.
+      def done(machine_state)
+        return nil unless machine_state.status == :done
+
+        Effect::Done.new(donedata: Predicator::UNDEFINED, donedata_error: nil,
+                         configuration: machine_state.configuration, **machine_state.counters)
+      end
+    end
+  end
+end

data/lib/statifier/position/shape.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Position
+    # The checks an import makes before it reads a state id, as the
+    # reference's import makes them (`check_required_keys/1` and
+    # `check_shapes/1` in statifier-ex): every key present, then each
+    # field's shape, the first that fails named; then every id resolved.
+    #
+    # @api private
+    module Shape
+      # A list of state ids.
+      ID_LIST = ->(value) { value.is_a?(Array) && value.all?(String) }
+
+      # One live invocation.
+      INVOCATION = lambda do |value|
+        value.is_a?(Hash) && value["state"].is_a?(String) && value["invoke_index"].is_a?(Integer) &&
+          value["invoke_id"].is_a?(String)
+      end
+
+      # A boolean.
+      BOOLEAN = ->(value) { [true, false].include?(value) }
+
+      # An integer.
+      INTEGER = ->(value) { value.is_a?(Integer) }
+
+      # Each history state's id to the ids it recorded.
+      HISTORY = ->(value) { value.is_a?(Hash) && value.all? { |key, ids| key.is_a?(String) && ID_LIST.call(ids) } }
+
+      # Each variable's name to its value's text.
+      TEXTS = ->(value) { value.is_a?(Hash) && value.all? { |key, text| key.is_a?(String) && text.is_a?(String) } }
+
+      # Each field's shape, in the order the fields are checked.
+      CHECKS = {
+        "configuration" => ID_LIST, "entered_states" => ID_LIST, "states_to_invoke" => ID_LIST,
+        "history_values" => HISTORY,
+        "active_invocations" => ->(value) { value.is_a?(Array) && value.all?(&INVOCATION) },
+        "invoke_counter" => INTEGER, "send_counter" => INTEGER, "timer_counter" => INTEGER,
+        "datamodel" => TEXTS,
+        "running" => BOOLEAN, "status" => ->(value) { %w[running done].include?(value) },
+        "macrostep" => INTEGER, "microstep" => INTEGER, "round" => INTEGER, "trace" => BOOLEAN,
+        "max_macrostep_rounds" => ->(value) { value == "infinity" || (value.is_a?(Integer) && value.positive?) }
+      }.freeze
+
+      module_function
+
+      # What makes `position` malformed, a detail Hash with its `kind`, or
+      # nil when it has the shape: not a Hash; required keys missing, every
+      # one named, sorted; or the first field of the wrong shape. A key that
+      # is not required is not looked at.
+      def failure(position)
+        return { kind: :not_a_hash } unless position.is_a?(Hash)
+
+        missing = KEYS.reject { position.key?(_1) }.sort
+        return { kind: :missing_keys, keys: missing } unless missing.empty?
+
+        field = CHECKS.find { |key, check| !check.call(position[key]) }&.first
+        { kind: :bad_shape, field: } if field
+      end
+
+      # Every id `position` names that `machine` holds no state for, once
+      # each, sorted.
+      def unknown_ids(machine, position) = named(position).reject { machine.id_to_index.key?(_1) }.uniq.sort
+
+      # Every state id a position's fields hold.
+      def named(position)
+        history = position["history_values"].flat_map { |key, ids| [key, *ids] }
+        position["configuration"] + position["entered_states"] + position["states_to_invoke"] + history +
+          position["active_invocations"].map { _1["state"] }
+      end
+    end
+  end
+end

data/lib/statifier/position/text.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Position
+    # A position's datamodel as text: each variable's value in predicator's
+    # tagged-value encoding (`Predicator::Tagged`), and back.
+    #
+    # @api private
+    module Text
+      module_function
+
+      # The datamodel's variables, sorted by name, each value encoded:
+      # `[texts, nil]`, or `[nil, failure]` naming the first variable, in
+      # that order, with no encoding and the codec's reason.
+      def encode(datamodel)
+        texts = {}
+        datamodel.keys.sort.each do |root|
+          encoded = Predicator::Tagged.encode(datamodel[root])
+          return [nil, { field: "datamodel.#{root}", reason: encoded.error.reason }] unless encoded.ok?
+
+          texts[root] = encoded.value
+        end
+        [texts, nil]
+      end
+
+      # The variables decoded, a deeply frozen Hash of new values: `[data,
+      # nil]`, or `[nil, failure]` for the first text, by name, that does not
+      # decode, or for a `_sessionid` that is not a String.
+      def decode(texts)
+        data = {}
+        texts.keys.sort.each do |root|
+          decoded = Predicator::Tagged.decode(texts[root])
+          return [nil, { kind: :undecodable_value, field: "datamodel.#{root}" }] unless decoded.ok?
+
+          data[-root] = decoded.value
+        end
+        return [nil, { kind: :no_session_id, field: "datamodel.#{SESSION_ID}" }] unless data[SESSION_ID].is_a?(String)
+
+        [Ractor.make_shareable(data), nil]
+      end
+    end
+  end
+end

data/lib/statifier/position.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "predicator/tagged"
+
+module Statifier
+  # Position export and import: a chart's execution between two calls, in
+  # the string-id vocabulary the reference moves a position in and out with
+  # (`Statifier.Position.export/1` and `import/2` in statifier-ex), written
+  # as plain data a host can keep as JSON. {Statifier.export_position} and
+  # {Statifier.import_position} answer through this module.
+  #
+  # A position is a Hash with String keys, the reference's required export
+  # keys in its order ({KEYS}), every value a String, an Integer, a
+  # boolean, an Array or a Hash of those:
+  #
+  # - `configuration`, `entered_states` and `states_to_invoke`: state ids,
+  #   sorted, the `<scxml>` root never named;
+  # - `history_values`: each history state's id to the ids it recorded,
+  #   sorted;
+  # - `active_invocations`: one Hash per live invocation, `state` (the id of
+  #   the state that owns the `<invoke>`), `invoke_index` (its ordinal
+  #   among that state's own) and `invoke_id`, sorted by state and index;
+  # - `invoke_counter`, `send_counter` and `timer_counter`: the sequences
+  #   behind the generated invoke ids, the generated send ids and the timer
+  #   ordinals;
+  # - `datamodel`: every variable, the system variables included, by name,
+  #   each value as text in predicator's tagged-value encoding
+  #   (`Predicator::Tagged`), which carries the dates, durations and the
+  #   undefined value JSON has no form for;
+  # - `running` and `trace`, booleans; `status`, `"running"` or `"done"`;
+  #   the counters `macrostep`, `microstep` and `round`; and
+  #   `max_macrostep_rounds`, a positive Integer or `"infinity"`.
+  #
+  # The reference's export carries the same keys as Elixir terms (sets,
+  # tuple keys, atoms) and an `identity`, the chart's content hash, name and
+  # version, which its import never reads. A machine here carries no
+  # identity, so a position carries none either, and an import loads a
+  # position onto any machine that holds every state it names, as the
+  # reference's does.
+  #
+  # Nothing of the driver's own is in a position, as the reference's
+  # position holds none of its session's: the virtual clock, the pending
+  # timers, the external queue, the sends a processor holds, a budget halt,
+  # the stopped chart's donedata, the state's last event selection, and the
+  # child sessions of its live invocations, their mailbox included. A
+  # position taken with a live child carries the invocation in
+  # `active_invocations`, as the core holds it, and nothing of the child, as
+  # the reference's session rebuilds its invocation table empty on a resume.
+  # An import starts them as a fresh start does: the clock at zero, no timer,
+  # nothing queued or held, no halt, no child; a send to such an
+  # invocation's id fails with `error.communication`, and no
+  # `done.invoke.<id>` arrives for it. The session id is the one the
+  # position's `_sessionid` holds, and the registered send types are the
+  # processors the host passes the import.
+  #
+  # A host reads {KEYS} and {Refusal} here; the bodies of the two calls
+  # ({Codec}) and the modules beneath them are private constants.
+  module Position
+    # The keys a position carries, in the reference's order, every one
+    # required by an import.
+    KEYS = %w[
+      configuration entered_states states_to_invoke history_values active_invocations invoke_counter
+      send_counter timer_counter datamodel running status macrostep microstep round trace max_macrostep_rounds
+    ].freeze
+
+    # The system variable the session id is read from.
+    SESSION_ID = "_sessionid"
+
+    # Why an export or an import was refused, the `error` of its
+    # {Statifier::Result}.
+    #
+    # @!attribute [r] reason
+    #   @return [Symbol] `:internal_queue_not_empty`, `:unnameable_states`
+    #     or `:unencodable_value` for an export; `:malformed_export` or
+    #     `:unknown_state_ids` for an import
+    # @!attribute [r] detail
+    #   @return [Hash] what the reason names, frozen: `indexes` for
+    #     `:unnameable_states`; `field` and the codec's `reason` for
+    #     `:unencodable_value`; `ids` for `:unknown_state_ids`; for
+    #     `:malformed_export`, a `kind` (`:not_a_hash`, `:missing_keys` with
+    #     `keys`, `:bad_shape`, `:undecodable_value` or `:no_session_id`,
+    #     each with `field`); empty for `:internal_queue_not_empty`
+    Refusal = ::Data.define(:reason, :detail)
+
+    # The bodies of the two calls. Internal, with the modules beneath.
+    module Codec
+      module_function
+
+      # {Statifier.export_position}'s body.
+      #
+      # @return [Result]
+      def export(state)
+        machine_state = state.machine_state
+        return refused(:internal_queue_not_empty) unless machine_state.internal_queue.empty?
+
+        unnameable = unnameable(machine_state)
+        return refused(:unnameable_states, indexes: unnameable) unless unnameable.empty?
+
+        datamodel, failure = Text.encode(machine_state.datamodel)
+        return refused(:unencodable_value, **failure) if datamodel.nil?
+
+        ok(exported(machine_state, datamodel))
+      end
+
+      # The indexes, sorted, other than the root's, that the state holds and
+      # that no id names: a state the document gave no id.
+      def unnameable(machine_state)
+        machine = machine_state.machine
+        referenced(machine_state).reject { _1.zero? || nameable?(machine, _1) }.sort
+      end
+
+      # Every state index a position's fields hold, once each.
+      def referenced(machine_state)
+        history = machine_state.history.flat_map { |key, recorded| [key, *recorded] }
+        invoking = machine_state.active_invocations.keys.map(&:first)
+        (machine_state.configuration + machine_state.entered_states + machine_state.states_to_invoke + history +
+          invoking).uniq
+      end
+
+      # Whether the document's id for the state at `index` names it.
+      def nameable?(machine, index)
+        id = machine.state(index).id
+        !id.nil? && machine.id_to_index[id] == index
+      end
+
+      # The position, deeply frozen.
+      def exported(machine_state, datamodel)
+        machine = machine_state.machine
+        Ractor.make_shareable(
+          { "configuration" => ids(machine, machine_state.configuration),
+            "entered_states" => ids(machine, machine_state.entered_states),
+            "states_to_invoke" => ids(machine, machine_state.states_to_invoke),
+            "history_values" => history(machine, machine_state.history),
+            "active_invocations" => invocations(machine, machine_state.active_invocations),
+            **counters(machine_state), "datamodel" => datamodel, **flags(machine_state) }
+        )
+      end
+
+      # The recorded history by id, sorted by the history state's id.
+      def history(machine, recorded)
+        recorded.map { |key, values| [name(machine, key), ids(machine, values)] }.sort.to_h
+      end
+
+      # The id of the state at `index`.
+      def name(machine, index) = machine.state(index).id
+
+      # The ids of the states at `indexes`, the root left out, sorted.
+      def ids(machine, indexes) = (indexes.uniq - [0]).map { name(machine, _1) }.sort
+
+      # The live invocations, sorted by their state's id and their index.
+      def invocations(machine, active)
+        entries = active.map do |(state_index, invoke_index), invoke_id|
+          { "state" => name(machine, state_index), "invoke_index" => invoke_index, "invoke_id" => invoke_id }
+        end
+        entries.sort_by { [_1["state"], _1["invoke_index"]] }
+      end
+
+      # The three sequences, as the position carries them.
+      def counters(machine_state)
+        { "invoke_counter" => machine_state.invoke_counter, "send_counter" => machine_state.sends.send_counter,
+          "timer_counter" => machine_state.sends.timer_counter }
+      end
+
+      # The fields after the datamodel, as the position carries them.
+      def flags(machine_state)
+        budget = machine_state.max_macrostep_rounds
+        { "running" => machine_state.running, "status" => machine_state.status.to_s,
+          **machine_state.counters.transform_keys(&:to_s), "trace" => machine_state.trace,
+          "max_macrostep_rounds" => budget == :infinity ? "infinity" : budget }
+      end
+
+      # {Statifier.import_position}'s body: the position checked, its
+      # datamodel decoded, every id it names resolved against `machine`, and
+      # the state rebuilt.
+      #
+      # @return [Result]
+      def import(machine, position, processors)
+        types = DRIVER_CHECKS.registered_types(processors)
+        failure = Shape.failure(position)
+        return refused(:malformed_export, **failure) if failure
+
+        datamodel, failure = Text.decode(position["datamodel"])
+        return refused(:malformed_export, **failure) if datamodel.nil?
+
+        unknown = Shape.unknown_ids(machine, position)
+        return refused(:unknown_state_ids, ids: unknown) unless unknown.empty?
+
+        ok(Rebuild.state(machine, position, datamodel, types))
+      end
+
+      # A successful result.
+      def ok(value) = Result.new(value:, error: nil)
+
+      # A refused result, its detail frozen.
+      def refused(reason, **detail)
+        Result.new(value: nil, error: Refusal.new(reason:, detail: Ractor.make_shareable(detail)))
+      end
+    end
+
+    require_relative "position/text"
+    require_relative "position/shape"
+    require_relative "position/rebuild"
+
+    private_constant :Codec, :Rebuild, :SESSION_ID, :Shape, :Text
+  end
+end

data/lib/statifier/validator/attributes.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Validator
+    # The check of the markup itself: an attribute name appears once on a
+    # tag (XML 1.0 section 3.1, "Unique Att Spec"). The reader keeps every
+    # repeated attribute and lowering keeps the first, so the repeat is read
+    # back out of the source: every start tag, markup inside `<content>`,
+    # `<assign>` and `<data>` included.
+    #
+    # @api private
+    module Attributes
+      module_function
+
+      # Each later occurrence of a name on one tag, at its own span; names
+      # are compared as written, prefix included.
+      def duplicates(_document, context)
+        parsed = XML.parse(context.source)
+        parsed.ok? ? element_duplicates(parsed.value) : []
+      end
+
+      # The repeats on `element` and on every element below it, in document
+      # order.
+      def element_duplicates(element)
+        seen = {}
+        own = element.attributes.filter_map do |attribute|
+          next seen[attribute.name] = nil unless seen.key?(attribute.name)
+
+          Findings.error(:duplicate_attribute, attribute.location, element: element.name, attribute: attribute.name)
+        end
+        own + element.children.grep(XML::Element).flat_map { element_duplicates(_1) }
+      end
+    end
+  end
+end

data/lib/statifier/validator/context.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Validator
+    # The index the checks share: built once per {Validator.validate} call
+    # from the chart and discarded with it, never kept or handed on.
+    #
+    # - `source`: the document as UTF-8, so that its byte offsets slice it;
+    # - `states`: every state in document order, a parent before its
+    #   children;
+    # - `by_id`: each named state by its id; a repeated id keeps the last
+    #   state written with it;
+    # - `parents`: each state's parent, another state or the {Document} for a
+    #   top-level one, keyed by the state node itself (by identity);
+    # - `transitions`: every transition, as `[transition, owner]`, in
+    #   document order; `owner` is `:plain` for a state's own, `:initial` for
+    #   one inside a state's `<initial>`, and `:history` for a history's own;
+    # - `invoke_content_markup`: whether a root that declares no namespace
+    #   is accepted.
+    #
+    # @api private
+    Context = ::Data.define(:source, :states, :by_id, :parents, :transitions, :invoke_content_markup) do
+      # Whether `state` sits inside `ancestor`, by the tree's structure: a
+      # state with no id, and two states that share one, are placed all the
+      # same.
+      def inside?(state, ancestor)
+        parent = parents.fetch(state)
+        parent.is_a?(Document::State) && (parent.equal?(ancestor) || inside?(parent, ancestor))
+      end
+    end
+
+    # Building the {Context}.
+    #
+    # @api private
+    module Index
+      module_function
+
+      # The {Context} of `document`, read from `source`.
+      def build(document, source, invoke_content_markup)
+        states = []
+        parents = {}.compare_by_identity
+        walk(document.states, document, states, parents)
+        by_id = states.each_with_object({}) { |state, ids| ids[state.id] = state unless state.id.nil? }
+        Context.new(source:, states: states.freeze, by_id: by_id.freeze, parents: parents.freeze,
+                    transitions: states.flat_map { owned_transitions(_1) }.freeze, invoke_content_markup:)
+      end
+
+      # Collects every state below `parent` in document order, with its
+      # parent.
+      def walk(children, parent, states, parents)
+        children.each do |state|
+          states << state
+          parents[state] = parent
+          walk(state.states, state, states, parents)
+        end
+      end
+
+      # A state's own transitions, then its `<initial>` element's; a
+      # history's own only.
+      def owned_transitions(state)
+        return state.transitions.map { [_1, :history] } if state.kind == :history
+
+        initial = state.initial_element&.transitions || Lowering::Reading::EMPTY
+        state.transitions.map { [_1, :plain] } + initial.map { [_1, :initial] }
+      end
+
+      # Whether `node` is a `<state>` or `<parallel>` with children to
+      # enter; the root is not.
+      def compound?(node)
+        node.is_a?(Document::State) && %i[state parallel].include?(node.kind) && !node.states.empty?
+      end
+    end
+  end
+end

data/lib/statifier/validator/data.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Validator
+    # The checks of `<donedata>`, `<content>`, `<param>`, `<datamodel>` and
+    # `<data>`.
+    #
+    # @api private
+    module DataChecks
+      # The rules of one `<data>`, in the reference's order.
+      DATA_RULES = {
+        data_expr_and_src: ->(data) { !data.expr.nil? && !data.src.nil? },
+        data_value_and_children: lambda do |data|
+          (!data.expr.nil? || !data.src.nil?) && !Lowering::Reading.blank?(data.text)
+        end,
+        data_reserved_id: ->(data) { data.id.start_with?("_") }
+      }.freeze
+
+      module_function
+
+      # `<donedata>` sits on a `<final>` only, and holds a `<content>` or
+      # `<param>` children, not both; each reported at the `<donedata>`.
+      def donedata(_document, context)
+        carriers = context.states.reject { _1.donedata.nil? }
+        both = carriers.select { |state| state.donedata.content && !state.donedata.params.empty? }
+        at_donedata(:donedata_not_on_final, carriers.reject { _1.kind == :final }) +
+          at_donedata(:donedata_content_and_params, both)
+      end
+
+      # The `reason` error of each state, at its `<donedata>`.
+      def at_donedata(reason, states) = states.map { Findings.error(reason, _1.donedata.location, id: _1.id) }
+
+      # A `<content>` under `<donedata>` or `<invoke>` does not carry both
+      # `expr` and a payload, markup or text that is not blank.
+      def contents(_document, context)
+        all = context.states.flat_map { [_1.donedata&.content, *_1.invoke.map(&:content)].compact }
+        all.filter_map do |content|
+          wording = payload(content)
+          Findings.error(:content_expr_and_text, content.location, wording:, expr: content.expr) if wording
+        end
+      end
+
+      # What a `<content>` with `expr` also carries: `"markup"`, `"text"`,
+      # or nil.
+      def payload(content)
+        return if content.expr.nil?
+        return "markup" if content.markup
+
+        "text" unless Lowering::Reading.blank?(content.text)
+      end
+
+      # A `<param>` under `<donedata>`, `<invoke>` or `<send>` carries exactly
+      # one of `expr` and `location`.
+      def params(_document, context)
+        state_params = context.states.flat_map { [*_1.donedata&.params, *_1.invoke.flat_map(&:params)] }
+        (state_params + Executable.sends(context).flat_map(&:params)).filter_map { param_error(_1) }
+      end
+
+      # The error of a `<param>` that writes neither or both, or nil.
+      def param_error(param)
+        written = [param.expr, param.param_location].compact.size
+        return if written == 1
+
+        Findings.error(written.zero? ? :param_no_value : :param_expr_and_location, param.location, name: param.name)
+      end
+
+      # `<data>`: not both `expr` and `src`, no child text beside either, no
+      # id beginning `_`; each at the id's span. Then each `<datamodel>` on a
+      # `<final>` or a history.
+      def data(document, context)
+        datamodels = [document.datamodel_element, *context.states.map(&:datamodel_element)].compact
+        datamodels.flat_map(&:data).flat_map { data_errors(_1) } + misplaced_datamodels(context)
+      end
+
+      # The errors of one `<data>`.
+      def data_errors(data)
+        location = States.span(data, :id)
+        DATA_RULES.select { |_, broken| broken.call(data) }.keys.map { Findings.error(_1, location, id: data.id) }
+      end
+
+      # A `<datamodel>` on a `<final>` or a history.
+      def misplaced_datamodels(context)
+        context.states.select { %i[final history].include?(_1.kind) && _1.datamodel_element }.map do |state|
+          Findings.error(:datamodel_bad_parent, state.datamodel_element.location, kind: state.kind)
+        end
+      end
+    end
+
+    # The checks of the root's namespace and version, and of the enumerated
+    # attribute values as written.
+    #
+    # @api private
+    module Enums
+      TRANSITION_TYPES = %w[internal external].freeze
+      BINDINGS = %w[early late].freeze
+      DATAMODELS = %w[predicator elixir null ecmascript xpath].freeze
+      AUTOFORWARDS = %w[true false].freeze
+
+      module_function
+
+      # The root resolves to the SCXML namespace (or, for invoke content
+      # markup, to none) and its version is `"1.0"`; each reported at the
+      # attribute's span, or the root's when it was not written.
+      def boilerplate(document, context)
+        namespace = document.namespace
+        namespace_ok = namespace == Findings::SCXML || (context.invoke_content_markup && namespace.nil?)
+        errors = namespace_ok ? [] : [Findings.error(:bad_namespace, States.span(document, :xmlns), uri: namespace)]
+        return errors if document.version == "1.0"
+
+        errors + [Findings.error(:bad_version, States.span(document, :version), version: document.version)]
+      end
+
+      # Every transition's `type`, the root's `binding` and `datamodel`, and
+      # every `<invoke>`'s `autoforward`, as written: lowering maps a value
+      # out of range onto the default, so only the text tells them apart.
+      def enums(document, context)
+        transitions = context.transitions.map(&:first)
+        invokes = context.states.flat_map(&:invoke)
+        transitions.flat_map { out_of_range(_1, :type, TRANSITION_TYPES, context, :transition_bad_type) } +
+          out_of_range(document, :binding, BINDINGS, context, :scxml_bad_binding) +
+          out_of_range(document, :datamodel, DATAMODELS, context, :scxml_bad_datamodel) +
+          invokes.flat_map { out_of_range(_1, :autoforward, AUTOFORWARDS, context, :invoke_bad_autoforward) }
+      end
+
+      # The `reason` error of a written attribute whose raw text is not in
+      # `allowed`; an attribute not written is its default, in range.
+      def out_of_range(node, key, allowed, context, reason)
+        location = node.attribute_locations[key]
+        return [] if location.nil?
+
+        raw = location.slice(context.source)
+        allowed.include?(raw) ? [] : [Findings.error(reason, location, raw: raw.freeze)]
+      end
+    end
+  end
+end