Publish-time checks: every runtime refusal and its twin

A runtime refusal for something a literal in the source could have told us is a bug in the publish check.

The packages in this family ship pure functions a host calls. The host's publish step is the gate: it runs those functions over a chart before the chart can start an execution, and it refuses the publish on what they report. An editor runs the same functions at edit time. The runtime checks described below stay in place as the backstop, and they are never the first line.

This page lists every refusal the family raises at run time, next to the publish-time function that finds the same defect first (its twin), or the word NONE when no function does. It covers three packages: statifier (this repo), statifier_router and statifier_blocks. Each package's section names the kinds of refusal it leaves out, and why. Every other refusal in the package is a row.

How to read the tables

Each row has five columns:

• Refusal - what happens at run time, and the event or return value that reports it.
• Raised by - the module (and, where it helps, the function) that raises it.
• Record - the decision record that governs it, by path in its own repo. In the statifier table the paths are in this repo. In the router and blocks tables they are in that package's repo.
• Literal? - whether a literal in the source decides the defect. "yes" means the defect is visible in the chart or configuration text, so a runtime refusal for it is a bug in the publish check. "no" means the defect depends on data, on another execution, or on a host's services, so the runtime check is the only possible check. "part" means the row splits, and the cell says where.
• Twin - the publish-time function, its package, and the version that ships it, or NONE.

A twin marked "main, next release" is on that package's main branch and not yet on Hex.

Only a literal can be checked. A typeexpr, targetexpr, eventexpr, srcexpr, or a document id computed by an expr is resolved against the datamodel at run time. Every twin below reports such a value as unchecked (or leaves it out) rather than guessing at it. The runtime check is the only check for such values.

statifier

error.execution and error.communication are platform events. The engine puts them on the execution's internal queue, and the chart handles them like any other event (docs/architecture.md, design principle 3, "Errors are events").

Five kinds of refusal in this package have no row, because none is a refusal of a chart at run time:

• The compile pipeline's own refusals: Statifier.compile/2 and what it runs (the parser, the lowering and Statifier.Validator). They are publish-time checks themselves.
• The stored-form codecs and the replay tool: to_binary and from_binary on Statifier.Chart, Statifier.Position, Statifier.Machine.Identity and Statifier.Session.Recording, Statifier.Position.export/1 and Statifier.Position.import/2, and Statifier.Replay.run/1. They refuse a blob or a recording a host stored, not a chart.
• Answers to a host's own call: Statifier.send_event/2 on a machine that is no longer running ({:error, :not_running}), Statifier.Session.recording/1 and subscribe/3 on a session that does not record, and the start options that Statifier.start_session/2 and Statifier.Session.start_link/2 refuse before an execution begins.
• A host handler's own perform/2 answer. Statifier.Session does not read what an invoke handler's perform/2 returns, and Statifier.Invoke.SyncHandler.Adapter.perform/3's {:session_not_registered, id} is that kind of answer. A sync handler's {:error, reason}, and the adapter's {:unknown_invoke_type, type}, do reach the chart: they are reported as S10.
• Each ArgumentError raised when a host breaks a contract: a send processor's ioprocessors_entry/1 that answers something other than a string-keyed map, a sync handler module that does not export invoke_types/0, or a :datamodel start option with a key the engine refuses. That is a host programming fault.

The build tasks under lib/mix/ are tooling and are not part of the runtime.

The one function a host calls for this table is Statifier.Publish.findings/2 (statifier 2.9.0): it runs every check this package holds over a compiled chart and the host's declaration, and returns findings that each name their row here (docs/adr/0073-one-publish-findings-function-holds-every-publish-time-check.md). It composes the twins of S1 and S15 and holds one check each for S2, S3, S6, S9, S11 to S14 and S16 to S19. A row that gains a check lands inside it as one check, and its cell changes when it does.

statifier_router

At the executor seam, a refusal on the send side reaches the sending execution as error.communication carrying the send's sendid (StatifierRouter.SendHandler). The step that made the send is still committed. The routing side's outcomes are what StatifierRouter.route/3 returns, and they are written to the binding's ledger.

A source invoke's refusals (RT15 to RT17) go back to the host's invoke handler, which decides how the chart hears of them.

A delivery's own errors (RT3, RT20, RT21 and RT24) are met on both sides. StatifierRouter.route/3 returns them, and a send to the execution target hears them as error.communication. That send's delivery rolls back to a savepoint of its own, and the sending step stands (StatifierRouter.Delivery.deliver_event/4).

Four kinds of router refusal have no row:

• Configuration-time checks, made before any event is routed: the constructors StatifierRouter.Config.new/1, StatifierRouter.Binding.new/1 and StatifierRouter.Resolver.Static.new/1; the ArgumentErrors StatifierRouter.Broadway.start_link/1 raises for its options, and whatever Broadway.start_link/2 itself answers; and the ArgumentErrors StatifierRouter.Migrations.up/1 and down/1 raise for their options.
• Each ArgumentError the router raises for a host callback that answers outside its contract (a resolver, a chart resolver, a delivery module, a StatifierRouter.Contracts.check/3 lookup), or for a schema handed to StatifierRouter.Config.queryable/2 or put_meta/2 that is not one of the package's. That is a host programming fault.
• The maintenance sweeps. StatifierRouter.Addresses.reap/3 refuses bad options and passes on an error from StatifierPersistence.Storage.fetch_execution/2, and a StatifierRouter.PinSource raises when it cannot count. Neither is a chart or a message defect.
• The publish-time functions themselves: StatifierRouter.Contracts and StatifierRouter.Routes.

statifier_blocks

A core.subchart names its child by a literal document id. When the child cannot start, the chart hears error.communication.invoke.<block id> carrying a reason. The in-memory handler, StatifierBlocks.Runtime.Subchart, raises that event itself with one of three reasons, and never answers {:error, _}, because the engine would turn that into an error.execution with no data and the reason would be lost. The durable handler, StatifierBlocks.Runtime.DurableSubchart, answers its dispatch with the same three reasons as a failure list, which statifier_persistence's driver turns into the same event; the driver adds a fourth reason of its own (B6).

Three kinds of refusal have no row. A core.map compiles to one <invoke>, and the fan-out handler that starts its children is not in this package (docs/adr/0009-fan-out-block-type.md): its refusals belong to the package that ships it. Every refusal outside lib/statifier_blocks/runtime/ belongs to authoring or to publishing: decoding, editing, compiling and the publish-time functions, which are the checks themselves, and StatifierBlocks.Runtime.FixtureRuns, which runs an author's fixtures. And each ArgumentError the two handlers raise for a host callback or a dispatch context outside its contract is a host programming fault.

A block document is also a chart once it compiles, so rows S1 to S19 apply to it too. Where statifier_blocks has its own check for one of those rows, that row says so.

An example: a library loan

A loan chart sends overdue notices through a processor the host registers under library:notices. The loan document's declaration names patron.blocked as an event it accepts, but no transition listens for it.

<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
       initial="on_loan" datamodel="predicator">
  <state id="on_loan">
    <transition event="loan.renew" target="on_loan"/>
    <transition event="loan.due" target="overdue">
      <send type="library:notices" target="overdue_notice" event="loan.overdue"/>
    </transition>
    <transition event="copy.returned" target="returned"/>
  </state>
  <state id="overdue">
    <transition event="copy.returned" target="returned"/>
  </state>
  <final id="returned"/>
</scxml>

A host whose publish step has not registered the processor, checking the chart against the names the loan document declares, gets two findings:

{:ok, machine} = Statifier.compile(loan_source)

Statifier.Send.Types.unsupported_sends(machine, nil) |> Enum.map(& &1.type)
#=> ["library:notices"]

Statifier.Chart.check_accepts(machine, ["loan.renew", "loan.due", "copy.returned", "patron.blocked"])
#=> %{unreachable: ["patron.blocked"], undeclared: []}

The first finding is S1. Without it the send would raise error.execution the first time a loan fell due. The second is S15. Without it a patron.blocked event sent to this execution would be discarded without a word.

Drop the type from the send and the chart still compiles, and unsupported_sends/2 returns []. The literal target="overdue_notice" is not a target the built-in processor can parse. The first time a loan falls due, the engine raises error.execution with data {:invalid_target, "overdue_notice"}. That is row S2, a runtime refusal that a literal could have prevented, and Statifier.Publish.findings/2 reports it before the chart runs: one finding of kind :invalid_target at the send's location.

Keeping this table true

The statifier rows come from this search over lib/, which finds every place the engine names error.execution or error.communication, in code or in prose:

grep -rn -E 'error\.(execution|communication)' lib/

and this one, which narrows it to the raise sites:

grep -rn -E 'raise_platform\(|\{:raise, :platform|error_name\(|Event\.(external|platform)\("error|"error\.communication"' lib/

Those two searches find the platform events. The census behind every table also ran this search over lib/ in each of the three packages, which matches every {:error in any form (a literal reason, a variable passed on, a callback's spec), every raise, every else clause of a with, and the router's and the blocks handlers' own outcome tags:

grep -rn -E '\{:error\b|\braise\b|^[[:space:]]*else\b|\{:(dropped|key_refused|send_refused|send_undelivered|refuse|failed)\b' lib/

A function that returns a callback's answer as its last expression carries no {:error of its own, so each callback whose spec the search matched was followed to the function that calls it. Every refusal the search led to is a row or falls in one of the kinds of refusal a section names as left out, except four that are open for a later revision of this page: a cond that evaluates to something other than a boolean; the refusals of the Statifier.Testing helpers; the write step's refusals from Predicator.ContextLocation.put/3 (predicator 9.0.0), :not_a_container and :invalid_index, which depend on the data because a negative index writes to a map and is refused only for a list; and a variable bracket key that is unbound or is neither a string nor an integer (:undefined_variable, :invalid_key).

A new raise site, a new refusal reason in a sibling package, or a new publish-time function changes a row here. So does a twin that moves from a main branch to a release.