Chart patterns: external-resource verdicts

This is a guide for a chart author whose document reaches an external resource - through an <invoke> handler (docs/extending.md) or an external <send> - and who has to decide what the chart does when that resource reports itself unavailable. A host's external connection or credential may be paused or revoked, a downstream service may be rate-limited or gone; the chart has to route somewhere on that news, explicitly.

Two canonical reactions cover the ground, and this document shows both in one runnable chart: park and retry for a resource that is temporarily unavailable, and fail fast for one that is permanently unavailable. The worked example is a card capture against a payment provider, but nothing in either pattern is specific to that - substitute your own verdict events and the shapes are unchanged.

The verdict is the host's; the chart just routes

The distinction between "temporarily unavailable" and "permanently unavailable" is not one the chart can make, and this engine will never make it on the chart's behalf. Only the host knows whether a refusal means "paused by an administrator, try later" or "revoked, never again" - that knowledge lives in the host's response codes, its configuration, its own records.

So the host renders the verdict and delivers it as events, and the chart's whole job is to route on them. Two delivery shapes work equally well:

• Distinct event names - the host's handler (or the code it enqueued) reports back with capture.deferred versus card.revoked, via Statifier.Session.send_event/2 or as part of its instruction plan. The chart routes on the event name alone. This is the shape the example below uses, because it keeps every arrow legible in the document.
• One event, payload routed with cond - the host sends a single capture.unavailable whose payload carries the verdict, and the chart splits with cond="_event.data.verdict == 'deferred'" arrows. Same pattern, one more level of indirection; prefer distinct names unless the verdict vocabulary is open-ended.

The engine's own error events follow the same posture. A planning failure in a handler (start/2 returning {:error, _}, or an unregistered type) is raised as error.execution; a registered handler that genuinely attempted communication and failed is error.communication (docs/extending.md, ADR-0051). Those are events like any other: give them explicit arrows too. Errors are events here, never silent defaults (ADR-0004's posture, carried through the whole engine): an unhandled error event is simply discarded, so a chart that omits the arrow has decided - silently - that failure changes nothing. Decide it out loud instead, with an arrow to a state whose name says what you decided.

error.communication is also how an asynchronous invocation reports that it is over for good. A handler-backed <invoke> whose work outlives the macrostep has no return value to route on, so its host says how it went through one of two doors: Statifier.Session.done_invocation/3 for work that finished, and Statifier.Session.failed_invocation/3 for work its retry policy has given up on. The second delivers error.communication.invoke.<invoke_id>, which the descriptor prefix rule makes match a plain error.communication arrow - so the arrow this section asks for already catches it. A chart that wants to park one invocation specifically names the full event instead (event="error.communication.invoke.inv_3"). ADR-0068 records the argument; docs/extending.md documents the door.

Note the division of labor this implies for the retry pattern below: a host-owned retry policy that gives up calls failed_invocation/3 once, and the chart hears a single terminal event. The chart-visible retry budget in Pattern 1 is the other arrangement - the host reports each attempt's verdict and the chart owns the budget. Pick one; running both means two retry loops nested inside each other.

Pattern 1: park and retry, with the budget visible as states

A temporarily unavailable resource deserves a retry - but a bounded one, with backoff, and both bounds belong in the document where a reader can see them. The pattern: each verdict arrow moves to a park state whose <onentry> schedules the next attempt with <send delay="...">; the retry budget is spelled as a chain of states rather than a counter, so exhaustion is a place in the chart, not an arithmetic overflow in handler code.

Keeping the budget in states rather than in handler code is the point of the pattern. The chart is the artifact that gets reviewed, versioned, and observed; a retry loop hidden in the host's handler is invisible to all three. When a session is parked, its configuration names which attempt it is parked after - useful in every trace and every debugger view.

The backoff schedule is the delay values on the park states' <send> elements. The example uses milliseconds so its test runs fast; a real chart says delay="30s" or delay="2h". For delays long enough that the session process may not outlive them, the same <send delay> becomes a durable timer by consuming the SendDelayed effect in your host - see docs/durable-timers.md; the chart does not change.

Pattern 2: fail fast, on an explicit arrow

A permanently unavailable resource - revoked, unauthorized, deleted - gets no retry loop. Retrying a revoked credential is not persistence, it is noise, and often actively harmful (lockouts, alarms). The pattern is a single explicit arrow from every state that could hear the verdict to a <final> state whose id says what happened. The host observes the :done effect (or done.state.* / the final configuration) and takes it from there.

The example chart

One document, both arms, in the card-processing domain: an authorized transaction being captured against a payment provider. Two deferred attempts are retried with growing delays; the third capture.deferred exhausts the budget. card.revoked fails fast from anywhere. error.execution - the engine's own verdict that the invocation could not even be planned - and error.communication - a registered handler that reached for the provider and failed, including an async invocation whose host called failed_invocation/3 - both fail fast on their own explicit arrows.

<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="capturing">
    <state id="capturing">
        <transition event="capture.succeeded" target="settled"/>
        <transition event="capture.deferred" target="parked_once"/>
        <transition event="card.revoked" target="needs_attention"/>
        <transition event="error.execution" target="needs_attention"/>
        <transition event="error.communication" target="needs_attention"/>
    </state>
    <state id="parked_once">
        <onentry>
            <send event="retry" delay="10ms"/>
        </onentry>
        <transition event="retry" target="retrying_once"/>
        <transition event="card.revoked" target="needs_attention"/>
    </state>
    <state id="retrying_once">
        <transition event="capture.succeeded" target="settled"/>
        <transition event="capture.deferred" target="parked_twice"/>
        <transition event="card.revoked" target="needs_attention"/>
        <transition event="error.execution" target="needs_attention"/>
        <transition event="error.communication" target="needs_attention"/>
    </state>
    <state id="parked_twice">
        <onentry>
            <send event="retry" delay="20ms"/>
        </onentry>
        <transition event="retry" target="last_attempt"/>
        <transition event="card.revoked" target="needs_attention"/>
    </state>
    <state id="last_attempt">
        <transition event="capture.succeeded" target="settled"/>
        <transition event="capture.deferred" target="needs_attention"/>
        <transition event="card.revoked" target="needs_attention"/>
        <transition event="error.execution" target="needs_attention"/>
        <transition event="error.communication" target="needs_attention"/>
    </state>
    <final id="settled"/>
    <final id="needs_attention"/>
</scxml>

Things to read off it:

• The budget is three attempts, and you can count them - capturing, retrying_once, last_attempt. Widening the budget is adding a park/retry pair, a reviewable diff, not editing a constant in host code.
• The backoff is visible - 10ms then 20ms, on the park states' <send delay> values, exactly where a reviewer would look for them.
• Exhaustion is an arrow, not an error - last_attempt's capture.deferred goes to needs_attention directly. Nothing counts down; the third deferral simply has nowhere left to park.
• The park states still hear the fatal verdict. A revocation that arrives while parked must not wait out the retry delay only to fail on the next attempt - parked_once and parked_twice carry their own card.revoked arrows.
• The two final states say what happened. settled and needs_attention are both <final>, and the host observes the :done effect either way; the names are what tell an operator whether anything is owed. Reaching a <final> also means the run's active configuration is empty afterwards - Statifier.active_leaf_states/1 returns an empty MapSet, which is how a finished run reads.
• In this example the attempt states only route. How an attempt is made is the host's side of the seam: typically each capturing-shaped state carries an <onentry> <send> (or the whole region sits under an <invoke type="myapp:capture">) that pokes the host, and the host answers with one of the verdict events. That half is omitted here so the pattern - the routing - stays the whole document.

Testing both arms

The chart above is runnable as written, with the same declarative runner this repository tests itself with (docs/testing-charts.md). The delayed sends route the test through a real Statifier.Session automatically; the verdict events are ordinary external events, which is the pattern's premise - the host's verdict needs no special machinery to simulate, because it is just events:

defmodule MyApp.CaptureVerdictChartTest do
  use Statifier.Testing.Case, async: true

  @chart """
  ... the document above ...
  """

  test "park/retry: the budget exhausts into the needs_attention final state" do
    test_scxml(@chart, "three deferrals exhaust the budget", ["capturing"], [
      {%{"name" => "capture.deferred"}, ["retrying_once"]},
      {%{"name" => "capture.deferred"}, ["last_attempt"]},
      {%{"name" => "capture.deferred"}, ["needs_attention"]}
    ])
  end

  test "fail-fast: a revoked card routes straight to needs_attention" do
    test_scxml(@chart, "revoked fails fast", ["capturing"], [
      {%{"name" => "card.revoked"}, ["needs_attention"]}
    ])
  end

  test "fail-fast: a permanently failed capture invocation parks the same way" do
    test_scxml(@chart, "exhausted invocation parks", ["capturing"], [
      {%{"name" => "error.communication.invoke.capture"}, ["needs_attention"]}
    ])
  end
end

Each capture.deferred step's expected configuration is the next attempt state, not the park state: the runner waits for the park state's short retry timer to fire before comparing. All three tests land on ["needs_attention"]

• the same final state, reached down three very different arrows, which is exactly the property worth pinning. The third is the ADR-0068 door arriving as an ordinary event: nothing in the chart names failed_invocation/3, it just routes on the event that door delivers, matched by prefix against the plain error.communication arrow.

This repository runs this exact document and both tests in test/statifier/chart_patterns_test.exs, so the example cannot drift from the engine's behavior without a red gate.

Where the pattern's pieces are specified

• Handler seam, error.execution versus error.communication, and why the engine never rescues a handler failure into a default: docs/extending.md and ADR-0051.
• Reporting an async invocation's completion or permanent failure back to the chart (done_invocation/3, failed_invocation/3, and error.communication.invoke.<invoke_id>): docs/extending.md and ADR-0068.
• Durable <send delay> for park delays measured in hours or days: docs/durable-timers.md and ADR-0054/0059.
• The no-eval, computation-lives-in-the-host posture that makes the verdict the host's in the first place: ADR-0004 and docs/datamodel.md.
• The declarative test runner: docs/testing-charts.md and ADR-0053.