The GenServer effect interpreter (ADR-0003): the outer while running loop, the waiting external events, the delayed-send timers, and the fan-out of the effect stream to subscribers. The pure core decides; this module performs.

This is the one module under lib/statifier/ allowed to do I/O (lib/mix/statifier/adr_guard.ex's @effect_interpreter_paths), which is why the deciding half lives in Statifier.Session.Inbox, Statifier.Session.Timers, and Statifier.Session.Effects - pure values and a pure function, testable with no process at all - and only the performing half lives here. A different path or module name fails the gate.

A bare start_link/2 stays legal; the runtime is opt-in

start_link/2 and the use GenServer-generated child_spec/1 still work exactly as before: an embedder can place a session directly in their own supervision tree, and :name is passed to GenServer.start_link/3 unchanged, so an embedder-owned {:via, Registry, _} works with no code here. A session started this way is legal and unregistered - ADR-0027 decision 2 sanctions this outright, since C.1 leaves "accessible to a given SCXML Processor" platform-defined, and an unregistered session is an inaccessible one to every other session (decision 10 below is the one exception, and it is about self-addressing, not registration).

Statifier.start_session/2 is the alternative that registers: it starts the session on Statifier.SessionSupervisor under Statifier.Supervisor (ADR-0027), and init/1 below registers under Statifier.Registry when that registry is running - never fatal to the session when it is not, so a bare start_link/2 embedder pays nothing for a runtime it never placed.

use GenServer, restart: :temporary (ADR-0027 decision 4) is written explicitly, both because the generated child_spec/1 otherwise defaults to restart: :permanent - which would have a supervisor restart a session that halted normally, the opposite of the next section - and because :temporary itself is a decision: a supervisor restart re-runs start_link/2, which generates a fresh sess_ id and loses every bit of the crashed session's state, so restarting is actively wrong, not merely useless. Recovery that preserves identity is replay, not a restart flag.

:done idles the session; it does not stop it

The process stays alive with the terminal %MachineState{} and the retained %Effect.Done{} in hand, so snapshot/1 and status/1 still answer after termination. Stopping is the caller's move (stop/2), or the supervisor's. Idle means inspectable, not still acting: further events are queued but never drained, and every pending delayed-send timer is cancelled at the halt itself (spec 6.2's discard-on-termination - discard_pending_timers/2 - not deferred to terminate/2, which an idled process may never reach). The same is true, with a narrower meaning, for :cancelled (cancel/1 reached the same exit_interpreter/1 path) and for :budget_exhausted (ADR-0019): the session neither retries with a larger budget nor stops itself, and cancel/1 still works from a budget-halted session, since the underlying %MachineState{} is still running and the inbox's cancel entry is checked before any drive of the core - a queued ordinary event is not. One asymmetry: because the interpreter has not exited under :budget_exhausted, its already-scheduled delayed sends stay armed and still deliver; they are discarded only when the eventual cancel/1 halts it :cancelled.

One subscriber stream

There is no :owner concept. Subscribers are a monitored set; start_link/2 takes :subscribers (default []), and subscribe/2/unsubscribe/2 manage it afterward. Every message a subscriber receives is {:statifier, session_id, message}, where message is one of:

• {:effect, effect} - every effect the core (or an interpret/2 caller) hands this session, trace effects included, in non-decreasing (macrostep, round) order - the same order Statifier.Replay produces for the same recording (ADR-0044 decision 1). An ADR-0039 re-entry crosses the seam at its own instruction's position but its effects are queued and drained after the batch that triggered it, so a subscriber never sees a later round ahead of an earlier one. Trace effects are ordinary list members here too, never a side channel.

  This is a guarantee about delivery order, not one a subscriber can re-derive from the structs: round is carried only by the Statifier.Effect.Trace.* payloads and by Statifier.Effect.BudgetExhausted today, so a mixed stream cannot be sorted back into this order after the fact (ADR-0044 decision 4 leaves stamping round onto the rest as follow-on work). Take the order as it arrives.

  A macrostep may carry more than one Trace.MacrostepStable - one per core drive that reached quiescence - and there is exactly one per (macrostep, round) (ADR-0044 decision 3). Within a macrostep the last one is that macrostep's last quiescent point, which is not always where the macrostep ends: a macrostep that halts ends with Trace.Done instead, either after its final Trace.MacrostepStable or - when the halting drive is the only one

  • with no Trace.MacrostepStable of its own at all.

• {:unroutable, effect} - reserved for an effect this session cannot route; every :send/:send_delayed/:invoke/:cancel_invoke/ :autoforward effect now routes (see Statifier.Session.Effects's own moduledoc), so no message currently reaches a subscriber this way.

• {:halted, :done | :cancelled | :budget_exhausted} - one lifecycle message, following the effects that caused it, and the last message this session sends its subscribers for the run (ADR-0044 decision 2).

A late subscriber catches up by replaying the recording, not from any buffer this session retains (ADR-0049). subscribe/3 with catch_up: true returns {:ok, recording} - the session's current Statifier.Session.Recording.t(), snapshotted in the same handle_call that adds the pid - or {:error, :not_recorded} without adding it, for a session not started with record: true.

The invariant that makes the split exact: between GenServer callbacks, Statifier.Replay.run/1 over this session's current recording produces exactly the messages this session has notified so far. Each callback is atomic in the effects' terms - it records its input and notifies every resulting effect, including ADR-0044's deferred re-entry batches drained before the callback returns, which is why deferred is documented always [] between callbacks - so a subscribe call, serialized between callbacks, observes a recording whose replay is precisely the notified prefix.

The consumption recipe, as it will actually be written:

{:ok, recording} = Statifier.Session.subscribe(session, self(), catch_up: true)
{:ok, %{stream: prefix}} = Statifier.Replay.run(recording)
# every subsequent {:statifier, session_id, message} is the suffix

ADR-0044 decision 1's monotone-arrival contract holds across the seam: the prefix is replay's own order and the suffix continues it. A halted session composes for free - the recording is complete, the replayed stream ends {:halted, reason}, the live suffix is empty, and Replay.run/1's status says so, so post-mortem attachment is the same call as late attachment. A subscriber wanting only the current picture keeps using snapshot/1/status/1 with a plain subscribe/2; nothing here replaces them.

A subscriber that dies is dropped on its own :DOWN.

A cancel is a queue entry, not an out-of-band call

cancel/1 enqueues the cancel marker onto this session's own external inbox (Statifier.Session.Inbox.enqueue_cancel/1), so a cancellation is recorded in the same ordered queue as every event (docs/observability.md constraint 6) rather than racing ahead of it through a side channel. Draining it runs Statifier.Interpreter.cancel/1

• Appendix D's running = false followed by exitInterpreter() - and halts the session :cancelled, even though the {:done, _} effect that walk produces is still forwarded to subscribers exactly as natural termination's is.

<send> routing

A <send>/<send_delayed> with no target lands on this session's own external queue. #_internal and a self-addressed #_scxml_<sessionid> (decision 10: a session is always accessible to itself, registry or not) both resolve with no registry at all - the former through Statifier.Interpreter.deliver_internal/5 (ADR-0039), the latter onto this session's own inbox. Every other #_scxml_<sessionid> resolves through Registry.lookup(Statifier.Registry, sid) (ADR-0027 decision 2): a hit casts the event onto that session's inbox via send_event/2; an empty lookup - the id never existed, named a bare unregistered session, or named a session that has since died - takes C.1's mandated error.communication path on the sending session's own internal queue, through the private communication_error/4 resolver. #_parent/_parent (6.4.4/C.1's spelling disagreement, decision 8) resolves through state.invoked_by: a live invocation's child stamps invokeid (5.10.1) and delivers straight to the parent's external queue; a session that was never invoked has no parent and takes the same communication_error/4 path as any other unreachable route. #_<invokeid> resolves through the same invocation table this module holds (Statifier.Session.Invocations, Invocations.fetch/2) rather than the registry: a live entry's pid gets the event delivered to its external queue directly, and an invokeid naming no live invocation - never one, or since cancelled or exited - takes the same communication_error/4 path as any other unreachable route. An unsupported type or an unparseable target raises error.execution the same way, at plan time. :cancel_invoke plans {:stop_child, invoke_id} ("Cancelling an invocation" below). A child reaching a top-level final returns done.invoke.<invokeid> to its parent's external queue the same direct way ("Starting an invocation's child session" below names the reciprocal obligation this halt-time delivery completes). See Statifier.Session.Effects and Statifier.Send.Target.

Autoforward delivery

{:autoforward, %Effect.Autoforward{}} plans {:forward, invoke_id, event} unconditionally (Statifier.Session.Effects) - every external event the parent removes from its queue, forwarded verbatim to each autoforwarding invocation, at the point 6.4.2 puts it: inside apply_invoke_passes/2's own turn, before the next Inbox.next/1. Performing it looks invoke_id up in state.invocations and send_event/2s the event unmodified; a miss - the invocation was cancelled or the child died between the core's pass and this instruction - is a silent no-op, not an error.

Starting an invocation's child session

{:invoke, %Effect.Invoke{}} with a supported type plans {:start_child, invoke, effect} (Statifier.Session.Effects). This is never performed from init/1: an initial configuration's own <invoke> would otherwise start the child through Statifier.start_session/2 while this session's own start is still being served by the same Statifier.SessionSupervisor, and that supervisor process cannot answer the inner call until it has answered the outer one. Every planned instruction - this one included, at whatever position Statifier.Session.Effects.plan/2 gave it - performs from handle_continue/2, one message-loop turn after init/1 returns. Performing it resolves invoke.content/invoke.src through Statifier.Invoke.Source (state.invoke_source, the embedder-supplied resolver from start_link/2 ADR-0038 hands off to), seeds the resolved child Machine.t()'s datamodel through Statifier.Session.Invocations.seed_datamodel/2 (spec 6.4.3's name-matched <param>/namelist seeding), and starts it on Statifier.SessionSupervisor via Statifier.start_session/2 with invoked_by: {self(), invoke.invoke_id}. Success monitors the child and records {pid, session_id, monitor_ref, autoforward} in state.invocations; either a resolve failure or a Statifier.start_session/2 failure raises error.communication on this session's own internal queue instead (Decision 4: 3.12.2 names <invoke> outright as a communication-error source), through the private invoke_error/4 resolver, and writes no table entry - "terminate the processing of the element without further action."

A session started with invoked_by: {parent_pid, invoke_id} (an invoked child) monitors parent_pid in turn: the parent's :DOWN stops this session (a child whose parent is gone has nobody to report to), and a monitored child's own :DOWN pops its entry from state.invocations - both checked ahead of the ordinary subscriber :DOWN clause.

start_link/2's :inherit_observers starts a child with this session's :trace and subscriber pids at the moment it starts (ADR-0050), rather than leaving observation to a post-hoc attach, because an attach cannot substitute here: start_link/2 runs Interpreter.initialize/2 to quiescence, and the child is started from inside the parent's own invoke pass, so a subscriber added after the child's pid is knowable has already missed that child's Trace.EntrySet, Trace.ContentExecuted, Trace.InvokePass, and Trace.MacrostepStable.

Cancelling an invocation

{:cancel_invoke, %Effect.CancelInvoke{}} - the core's own reaction to a state exiting while one of its <invoke>s is still live - plans {:stop_child, invoke_id} unconditionally (Statifier.Session.Effects). Performing it pops invoke_id's table entry before touching the child, Process.demonitor/2s the ref with [:flush], and calls this module's own cancel/1 on the child - never stop/2: 6.4.3 requires the cancelled session to "exit at the end of the next microstep" having "execute[d] the <onexit> handlers for all active states", which is Interpreter.cancel/1's own exit_interpreter/1 walk, and GenServer.stop/2 would skip every one of them. The child is left to idle :cancelled exactly as any cancelled session does; this session is no longer monitoring it and no longer holds its id, so it is silent by construction. A miss - the invocation already popped by its own :DOWN, or a second cancel of the same id - is a silent no-op.

Popping the entry first is what makes the drain-time discard below correct: any event this child already delivered is un-keyed the instant the pop happens, not only once the cancelled child actually halts.

The discard of a cancelled invocation's queued events

6.4.3: after cancelling, this session "MUST ignore any events it receives from that session. In particular it MUST NOT ... insert them into the external event queue of the invoking session" (the doubled "not" is verbatim in the REC). handle_continue(:drain, _) applies this at the one point every queued entry passes through it: an {:invoked_event, invoke_id, _} entry whose invoke_id is no longer a key of state.invocations is dropped and the drain continues, with no separate retired-id bookkeeping - the live table is already the predicate (the invoke child-session plan's own Decision 6), and cancelling removes the key, so every event from that invocation - queued before the cancel or arriving after it - is dropped this way.

The predicate reads the entry kind, which send_invoked_event/3 sets only on the child-to-parent direction, and never event.invokeid. 6.4.2 requires an autoforwarded copy to preserve every 5.10.1 field, so an event this session forwards to one of its children arrives there still carrying a sibling invocation's invokeid - an id that names nothing in the receiving session's own table. Keying the discard on that field would drop exactly the copy 6.4.2 requires be delivered; keying it on where the entry came from is also what ADR-0027 already says ("every queued entry originating from a cancelled invokeid").

Statifier.Session.Inbox still needs no keyed discard of its own: the predicate is applied to Inbox.next/1's result, not inside the queue, which is what keeps Inbox ignorant of the invocation table even while it carries the entry's origin.

terminate/2 cancels every entry still in state.invocations alongside its existing timer cancellation, so an orderly stop of this session leaves no orphaned children; the child-side parent monitor above already covers the disorderly case.

Two snapshot shapes

snapshot/1 returns the whole %MachineState{} - the complete, resumable position tooling and replay need. status/1 returns a small projection for a caller polling in a loop, since snapshot/1 copies the entire compiled machine on every call. For a halted session, the projection's configuration is read from the retained %Effect.Done{} rather than %MachineState{}.configuration, which exit_interpreter/1 empties by construction - mirroring the restore test/support/case.ex performs for the same reason.

interpret/2 is a public seam, not a test hook

Decided by ADR-0029; see its own @doc for the recording contract it carries.

Recording taps the input clauses, never the inbox

:record (start_link/2) builds a Statifier.Session.Recording.t() that each of the five input-handling clauses appends one entry to, before that entry's effects are ever planned or performed - the same "one recordable input path" the converging-paths comment above handle_info/2's fired-timer clause already describes. ADR-0029 named the four inputs a sound recording needs; ADR-0034 decided replay re-derives core effects and re-injects interpret/2 batches rather than replaying against a live session, which is why the tap sits on the input side and not on the effect stream notify/2 fans out. recording/1 reads the value back; see its own @doc for the ordering caveat on when it is safe to call.