@spec check_accepts(machine :: Statifier.Machine.t(), declared :: [String.t()] | nil) ::
  accepts_check()

Compares declared, the event names a chart is declared to accept, with the chart's event vocabulary (events/1).

A descriptor matches a declared name under the descriptor semantics transition selection uses: Statifier.Interpreter.NameMatch.name_match?/2 over the descriptor's tokens and the name's tokenize/1 tokens, on token boundaries. A declared loan.renew is matched by the descriptor loan.renew, by loan.*, by loan., by loan and by *, and not by loan.renewal or loan.renew.late. One relation answers both lists:

• unreachable - each declared name that no descriptor in the vocabulary matches, in the declaration's order and without duplicates: a name the declaration promises and the chart can never select on.
• undeclared - each descriptor in the vocabulary that matches no declared name, in events/1's order: a name the chart listens for that the declaration does not state.

A declared entry is a name, not a descriptor: a * in it is an ordinary token and never a pattern, so a declared loan.* is matched by the descriptor loan but not by loan.renew. An empty list is a declaration that the chart accepts nothing: unreachable is [] and undeclared is the whole vocabulary.

With nil - no declaration - the computed vocabulary is the contract, which cannot disagree with itself, so both lists are empty. A host asking whether one name n is in a chart's computed vocabulary calls check_accepts(machine, [n]) and reads unreachable: [] means some reachable descriptor matches n, and [n] means none does.

The function reports and refuses nothing; which list a host refuses a publish on, if either, is the host's decision. Pure and total over a %Statifier.Machine{} and a list of strings or nil; like events/1 it reads no source text and needs no identity or source on the machine.

@spec events(machine :: Statifier.Machine.t()) :: [String.t()]

The chart's event vocabulary: every event descriptor on a transition whose source state can be active, computed from the compiled machine alone.

Each descriptor is returned as authored - its dot-split tokens joined back with ., so loan.renew returns loan.renew and loan. returns loan.. A pattern is reported as a pattern, never expanded: * and loan.* come back as written, and the function never guesses which names a pattern stands for. Platform and internal descriptors (done.state., error., a name the chart raises itself) are descriptors the chart listens for and are included. An eventless transition contributes nothing; a chart with no transition carrying an event answers [].

Descriptors appear in t_index order (states in document order, each state's own transitions before its children's), and within one event attribute in the order written; a descriptor equal, as a string, to one already returned is dropped. A document given inline to <invoke> is its own chart and is not read.

"Can be active" is a static rule over the chart's structure: a state some path enters, its ancestors included. It follows Appendix D's addDescendantStatesToEnter and addAncestorStatesToEnter. The root is entered by its default. Entering a state by its default enters it and then its initial states as targets (a compound state or the root), every child that is not a history by its default (a parallel state), or its history_default transition's targets as targets (a history pseudo-state). Entering a state as a target enters it by its default, enters each of its proper ancestors, and, for each parallel ancestor, enters by its default every child region that holds none of the transition's targets. Every transition in an entered state's transitions enters its targets as targets. A transition's cond and event are not read, so a transition whose condition is never true in practice still counts. A state's descriptors join the vocabulary when it is entered and is not a history pseudo-state.

So a transition on an ancestor of an active state is in the vocabulary, a descriptor on a state no path enters is not, a history's default target counts as entered, and every region of a reachable parallel state is reachable. The rule over-counts and never under-counts: a descriptor missing from the answer is one the chart can never select on.

Pure and total over a %Statifier.Machine{}; it reads no source text and needs no identity or source on the machine.

@spec format_version() :: pos_integer()

The version tag to_binary/1 writes and from_binary/1 checks. A bare integer, so a future format change is a version bump here rather than an inference from the blob's shape.

@spec from_binary(blob :: binary()) ::
  {:ok, Statifier.Machine.t()}
  | {:error, :not_a_statifier_blob}
  | {:error, {:unsupported_format_version, term()}}
  | {:error, {:compile_failed, [Statifier.error()]}}
  | {:error,
     {:identity_mismatch, expected :: Statifier.Machine.Identity.t(),
      actual :: Statifier.Machine.Identity.t() | nil}}

Decodes a to_binary/1 envelope and recompiles it into a Machine.t().

Checks run in this order, and the order matters: decode safely, then check the envelope's tag and shape, then its format version, then recompile the stored source under the stored options through Statifier.compile/2, then compare the recompiled Machine's identity against the blob's own. Version before recompile before identity, because the identity being checked is the recompiled Machine's - there is no identity to compare until the recompile has run, and a version this build cannot read at all should report as a version mismatch rather than failing to compile for reasons that have nothing to do with the source.

{:error, {:compile_failed, errors}} carries Statifier.compile/2's own [Statifier.error()] list unchanged - a blob whose source no longer compiles under this build (for instance a validator check tightened across a library upgrade) is a real, distinct failure and must not be flattened into :not_a_statifier_blob.

{:error, {:identity_mismatch, expected, actual}}'s expected is the blob's own stored identity and actual is the recompiled Machine's - Position's own argument order. Both are compared with Statifier.Machine.Identity.matches?/2, never ==/2 on the struct (ADR-0052 decision 1): a future identity field addition should not silently change what "the same chart" means at this call site either.

Returns {:error, :not_a_statifier_blob} for anything that is not this module's tagged envelope - a foreign term_to_binary blob, garbage bytes, or a well-formed envelope whose source is not a binary or whose opts are not a keyword list.

@spec to_binary(machine :: Statifier.Machine.t()) ::
  {:ok, binary()} | {:error, :unidentified_chart}

Encodes machine as a tagged, versioned binary envelope carrying its SCXML source, its persisted compile_opts, and its Statifier.Machine.Identity.t()

• never a compiled term.

Returns {:error, :unidentified_chart} when machine.identity or machine.source is nil - a Machine built without either (for instance one that came straight from Statifier.Compiler.compile/1 rather than Statifier.compile/2) has nothing for from_binary/1 to recompile from or check a future load against, so no blob is produced for it at all.

The payload is machine.source and machine.compile_opts verbatim, never machine itself - the whole point of this module is that a chart's binary form holds nothing Statifier.compile/2 cannot reproduce, which is what keeps the blob far smaller than term_to_binary(machine) for the same chart: the compiled states, transitions, and expressions are the overwhelming majority of a Machine's bytes.