Run-to-quiescence over StatifierPersistence.Runs: the loop that answers the chart's <invoke> calls and keeps stepping until it stops asking.

StatifierPersistence.Runs steps a run once. That is the durable unit and it is deliberately small - load, step, hand the effects to an executor, persist - but it is not what a host wants to call. A chart that invokes a service is not finished when the step that emitted the <invoke> returns: it is waiting for an answer it has no way to fetch for itself. Every host that has embedded this package has written the same loop on top - step, collect the calls, perform them, feed each answer back, step again - and every hand-written copy of it is a place where a durable run can quietly stop meaning what the same chart means under Statifier.Session.

This module is that loop, with the event construction taken from Statifier.Session's own rather than reinvented beside it.

What one drive does

One call to create/3 or send_event/4 is:

1. one StatifierPersistence.Runs entry point - the durable step, with the run's whole fetch-to-persist tail inside its serialization strategy;
2. every non-lifecycle effect through the host's :effects executor, in list order, exactly as Runs already hands them over;
3. every {:invoke, _} effect also through the host's :dispatch fun, synchronously, inside that same tail;
4. after the tail has returned - never inside it - one further Runs.step/5 per answer, in the order the calls were made, each of which can produce answers of its own;
5. repeat from 4 until no answer is left. The result is the last step's own result.

The ordering in 3 and 4 is forced rather than stylistic. Dispatch runs inside the tail because a call the chart made and a call the host performed have to be the same event in the same durable step; stepping runs outside it because the tail is already inside the run's serialization strategy, and a step issued from within would ask for exclusion its own caller is holding.

Answers are events, and they are Session's events

Statifier.Session gives a handler-backed invocation's host exactly two doors: Statifier.Session.done_invocation/3 and, per st-ADR-0068, Statifier.Session.failed_invocation/3. Both build an external event and enqueue it. This module builds the same two events, field for field, from the same Statifier.Evaluator.SystemVariables writers:

• {:ok, donedata} from :dispatch becomes done.invoke.<invoke_id>, carrying donedata as its data, its invokeid, and C.1's origin/origintype pair.
• {:error, failure} becomes error.communication.invoke.<invoke_id>, whose data is st-ADR-0068's three string keys - "reason" (default "unknown"), "attempts" and "detail" (both :undefined when the host supplies none, never nil) - built from the same failure keyword list failed_invocation/3 reads.

origin is #_scxml_<session id>, and the session id comes from the run's own persisted _sessionid (spec 5.10, st-ADR-0008), which Statifier.Position carries in the datamodel across a restart. A resumed run therefore answers with the same origin the run started with, on a node that has never seen it before.

The error arm is permanent failure, in st-ADR-0068's sense: the host's retry policy is exhausted and no done.invoke will follow. A transient failure is the host's to retry inside :dispatch before answering, not something to report to the chart.

What is not answered

A buffered answer is dropped rather than delivered when its invocation is no longer live by the time its turn comes - spec 6.4.3's drain-time discard, read off machine_state.active_invocations the same way Statifier.Interpreter reads it. A step that cancelled an invocation therefore takes that invocation's answer with it, which is what a session does.

<invoke type="scxml"> is handed to :dispatch like any other type.

Durable subcharts

A durable driver holds no child session between steps, so a subchart cannot be answered the way Statifier.Session answers one - by starting and holding a child session in memory. :dispatch answers a subchart instead: {:start_child, invoke, {:invoke, invoke}}, the same instruction Statifier.Session.Effects plans and that the built-in Statifier.Invoke.Handler.Scxml and StatifierBlocks.Runtime.Subchart both emit, unchanged, whichever session executes it. This module is the durable executor for it (ADR-0008 decision 3): it resolves and creates the child as an ordinary run, linked to this invocation under a reserved-namespace pin of the child's own chart identity (StatifierPersistence.Run.Linkage, ADR-0008 decision 2), drives that run to its own quiescence through this same loop - so a child that itself invokes a grandchild is handled with no extra code - and then answers :pending under ADR-0007 decision 1, exactly as any other asynchronous call does: the parent rests with the invocation live and no process holding it. The instruction is never renamed or reshaped, which is what makes a chart portable between the in-memory and durable paths.

Invocations answered later

A host whose service does not answer inside the drive - an enqueued job, a webhook, anything that outlives the process that started it - answers :pending from :dispatch instead. The call has been started; nothing is buffered for it; the drive rests and the position persists with the invocation still live in machine_state.active_invocations. There is no process holding the run in the meantime, which is the point: the run can wait days and survive a deploy.

The answer arrives later through done_invocation/5 or failed_invocation/5 - the two doors Statifier.Session gives a live session's host, on the durable path and keyed by the same invoke_id. They build the same two events the in-drive path builds and drive the run from them, so a chart cannot tell which way its answer came.

The cancel-versus-completion race

An invocation the chart cancels while its call is still running has an answer coming for something that is no longer live - across a restart, on a node that has never seen the run. The liveness read that settles it is active_invocations, which Statifier.Position persists and Statifier.Interpreter.ExitEntry empties when the invoking state is exited, and it is taken inside the run's serialization strategy: the door hands StatifierPersistence.Runs.step/5 an event builder rather than an event, and the builder reads the loaded position under the same exclusion the step itself holds. A check taken before the call would leave a window for a cancel to land between the read and the step.

A cancelled invocation's answer is {:discarded, run} - spec 6.4.3's discard again, the same rule the in-drive loop applies at drain time - and the chart never sees it.

This makes re-entry idempotent for the ordinary chart, which transitions out of the invoking state on its answer: the second delivery finds the invocation gone. It does not make it idempotent for a chart that stays in the invoking state after answering, because the core removes an entry from active_invocations on exit and on nothing else. That is the in-drive path's behavior too, not something the doors introduce, and it is where a host's own delivery-once discipline belongs (ADR-0007).

Bounding the loop

A chart whose answer re-arms the call it answered would drive forever. :max_turns (default 1000) bounds the answer-fed steps in one drive and returns {:error, {:turns_exhausted, max_turns}} when it is reached. The run is durable and quiescent at that point - every step that ran, persisted - so the error names a loop this driver refused to keep turning, not a lost position.

Example

driver =
  StatifierPersistence.Driver.new(store, machine,
    dispatch: fn type, params, _context -> MyApp.perform(type, params) end,
    effects: fn effect, _context -> MyApp.Timers.consume(effect) end,
    invoke_types: Statifier.Invoke.Types.new(types: ["myapp:authorize"]),
    serialization: {MyApp.RunLock, MyApp.RunLock}
  )

{:ok, run, machine_state} = StatifierPersistence.Driver.create(driver, run_id)

{:ok, run, machine_state} =
  StatifierPersistence.Driver.send_event(driver, run_id, Statifier.Event.external("go"))