@spec answer_parent(
  driver :: t(),
  child_run_id :: StatifierPersistence.Runs.run_id(),
  donedata_or_failure :: {:done, term()} | {:failed, keyword()}
) ::
  result() | :ok | :no_parent | {:error, StatifierPersistence.Storage.error()}

Answers child_run_id's parent with its completion or permanent failure (ADR-0008 decision 3) - a separate drive under the parent's own exclusion, driver.machine must be the parent's chart.

donedata_or_failure is {:done, donedata} or {:failed, failure}. Reads child_run_id's own linkage through parent_link/2 first: :no_parent is a no-op answering :no_parent, so this is safe to call on any run id, linked or not.

A child of a fan-out answers no parent here. Its linkage carries a child_count, so this call settles instead - records the child's own answer and, if it is the last, assembles the invocation's dense list and answers the parent's door once - and returns :ok. The routing is here and not only on the automatic path because a host driving the doors itself must not be able to bypass a settlement by calling this function: answering a fan-out's parent with one child's donedata would complete the whole map block on the first child to finish.

Public so a host with no chart_resolver: can call it explicitly with a driver built over the parent's own chart - the same construction the automatic path (wired into create/3, send_event/4, done_invocation/5 and failed_invocation/5) uses once its chart_resolver: has resolved one. The parent's answer is done_invocation/5 or failed_invocation/5 under the parent's own exclusion: a parent that has already cancelled the invocation answers {:discarded, _} here, which is ADR-0007 decision 3's mechanism doing its job, not an error.

@spec create(
  driver :: t(),
  run_id :: StatifierPersistence.Runs.run_id(),
  opts :: keyword()
) :: result()

Creates the run under run_id and drives it to quiescence.

StatifierPersistence.Runs.create/4 with this driver's executor, then the answer loop. opts takes everything create/4 takes except executor:, which this module supplies - initialize:, metadata:, routes:, and per-call overrides of the driver's own invoke_types: and serialization:.

@spec done_invocation(
  driver :: t(),
  run_id :: StatifierPersistence.Runs.run_id(),
  invoke_id :: String.t(),
  donedata :: term(),
  opts :: keyword()
) :: result()

Answers a :pending invocation with donedata and drives the run to quiescence.

Statifier.Session.done_invocation/3's door on the durable path: it builds the same done.invoke.<invoke_id> event, from the run's own persisted _sessionid, and steps it. invoke_id is the <invoke> element's id - the invoke_id :dispatch was handed in its dispatch_context/0.

Answering an invocation the chart has since cancelled is {:discarded, run}, spec 6.4.3's discard, decided from the loaded position inside the run's serialization strategy (the moduledoc's cancel-versus-completion section). So is answering a terminal run.

The answer can re-arm calls of its own; they are dispatched and driven exactly as send_event/4 drives them, :pending included.

opts takes what send_event/4 takes.

@spec failed_invocation(
  driver :: t(),
  run_id :: StatifierPersistence.Runs.run_id(),
  invoke_id :: String.t(),
  failure :: keyword(),
  opts :: keyword()
) :: result()

done_invocation/5's failing counterpart: answers a :pending invocation with a permanent failure and drives the run to quiescence.

Statifier.Session.failed_invocation/3's door on the durable path, building the same error.communication.invoke.<invoke_id> event from st-ADR-0068's failure keyword list (:reason, :attempts, :detail). Permanent in that record's sense: the host's retry policy is exhausted and no done.invoke will follow. A transient failure is the host's to retry before answering, not something to report to the chart.

Discards, re-armed calls and opts are done_invocation/5's.

@spec new(
  store :: StatifierPersistence.Storage.t(),
  machine :: Statifier.Machine.t(),
  opts :: keyword()
) :: t()

Builds a driver over store and machine.

opts:

• dispatch: (required) - the dispatch/0 fun every <invoke> is performed through.
• effects: - a StatifierPersistence.Executor.t/0 handed every non-lifecycle effect before the invoke dispatch, for the effects the host observes or persists itself (a <send delay=...> becoming a durable timer, a trace becoming a feed row). Defaults to nil, "the host wants none of them"; an {:error, reason} from it re-enters the chart as error.communication exactly as it does through StatifierPersistence.Runs directly.
• invoke_types: - the Statifier.Invoke.Types.t/0 snapshot stamped on every step. A driver-level default rather than a per-call one because the registered set is fixed for a session's lifetime (st-ADR-0051); routes:, which is not, stays per call. Defaults to nil, "the built-in set only".
• serialization: - the {module, config} per-run strategy every entry point runs inside (ADR-0004 decision 5). Defaults to whatever StatifierPersistence.Runs defaults to, the adapter's own lock_run/3.
• chart_resolver: - chart_resolver/0, how this driver reaches a chart it does not hold: (content_hash -> {:ok, Statifier.Machine.t()} | :error). It exists for exactly one purpose - answering a durable subchart's parent, whose chart is not this driver's machine (ADR-0008 decision 3). This package cannot supply it: a stored chart_blob is opaque by ADR-0003 decision 1 and nothing here decodes one, so the host that saved the chart is the only party that can compile it. Defaults to nil, "this driver answers no parents" - a host without one calls done_invocation/5 or failed_invocation/5 itself, from parent_link/2 and the drive's own run.donedata or run.failure.
• child_canceller: - child_canceller/0, how a :first_error settlement reaches the scheduler holding the start jobs of a fan-out's not-yet-started children. Defaults to nil, "this driver cancels no start jobs".
• max_turns: - the answer-fed steps one drive will take before refusing to take another. Defaults to 1000.

Every one of these except dispatch: may be overridden per call by passing the same key in a create/3 or send_event/4 opts list.

@spec parent_link(
  store :: StatifierPersistence.Storage.t(),
  run_id :: StatifierPersistence.Runs.run_id()
) ::
  {:ok, StatifierPersistence.Run.Linkage.t()}
  | :no_parent
  | {:error, StatifierPersistence.Storage.error()}

The "find my parent" query: reads run_id's own stored linkage, one key read off its fetched record (StatifierPersistence.Run.Linkage, ADR-0008 decision 2).

:no_parent for a run with no linkage - an ordinary run, or a durable subchart child that has none for whatever reason - not a failure: having no parent is an ordinary property of a run.

@spec send_event(
  driver :: t(),
  run_id :: StatifierPersistence.Runs.run_id(),
  event :: Statifier.Event.t(),
  opts :: keyword()
) :: result()

Delivers one external event to the run under run_id and drives it to quiescence.

StatifierPersistence.Runs.step/5 with this driver's executor, then the answer loop. An event delivered to a terminal run is that function's own {:discarded, run}, before any position decode and before any dispatch.

@spec start_child_at(
  driver :: t(),
  parent_run_id :: StatifierPersistence.Runs.run_id(),
  effect ::
    Statifier.Effect.Invoke.t()
    | {:start_child, Statifier.Effect.Invoke.t(),
       {:invoke, Statifier.Effect.Invoke.t()}},
  index :: non_neg_integer(),
  count :: pos_integer(),
  opts :: [{:policy, StatifierPersistence.Run.Linkage.policy()}]
) :: :ok | {:refused, term()}

Starts child index of count for parent_run_id's <invoke> - the public start-with-index door a scheduler drives a fan-out through (sp-t57, ruling C4; mirrors sob-q3y).

The single-child durable-subchart path creates its child from inside the parent's own step, because there is exactly one and the parent is already exclusive. A fan-out cannot: N children created inside the parent's step would hold the parent's exclusion for N creates. So the parent's step enqueues the fan-out instead, and each child is created later, from whatever job picks it up, through this function. That is the reading of statifier_blocks ADR-0008 decision 4 the fan-out needs: what happens under the parent's exclusion is the enqueue, and the children are created afterwards, idempotently and resumably.

Idempotent, and that is what makes it resumable: the child's run id is StatifierPersistence.Run.Linkage.child_run_id/3 of the same three values, so a re-delivered start job finds the child it already created and adopts it rather than creating a second one - exactly as the single-child path's at-least-once re-drive does.

Arguments

• driver - any driver over the right store. Its machine is not read: the child's chart comes from effect, and the parent's comes from the chart_resolver: when the settlement answers.
• parent_run_id - the run whose <invoke> this fans out.
• effect - the resolved Statifier.Effect.Invoke.t/0, or the whole {:start_child, resolved, {:invoke, invoke}} instruction a subchart handler answers with. The invocation id is read off it, so a caller passes no id separately.
• index - the child's 0-based position in the list being mapped over.
• count - N, recorded on every child so a settlement knows how many to wait for.
• opts - policy: (:all, the default, or :first_error).

index outside 0..count - 1 raises ArgumentError - a caller bug, not a storage event. The check is StatifierPersistence.Run.Linkage.new/6's, which is the one definition site of the linkage's own shape; this function does not repeat it.

Refusals

{:refused, reason}, the same shape and the same telemetry the single-child path's refusal at open uses, with three added arms. An adapter that cannot enumerate children refuses :child_listing_unsupported as it always has; one that cannot store a run's outcome payload refuses :run_outcome_unsupported, and one that cannot answer the indexed status projection refuses :run_states_unsupported. All three are the same principle: a child whose invocation could never be settled is not started. A parent_run_id naming no stored run refuses :run_not_found.