@spec cancel(
  store :: StatifierPersistence.Storage.t(),
  run_id :: run_id(),
  opts :: keyword()
) ::
  {:ok, StatifierPersistence.Run.t()}
  | {:discarded, StatifierPersistence.Run.t()}
  | {:error, error()}

Cancels a run: the second host-driven terminal transition (ADR-0004 decision 6 as extended by ADR-0008 decision 5), and the one a cascading cancel writes through.

Cancellation retains: no record and no position is deleted, no interpreter is involved, and the stored position is left untouched - only the record's status changes, to :cancelled. A run that is already terminal - cancelled by an earlier, interrupted cascade included - is discarded with {:discarded, run}, which is what makes re-running a cascade over an already-cancelled subtree a no-op.

opts accepts serialization: only - fail/4's serialization:, without its driver:: no chart is stepped by a cancel, on either side of a linkage.

@spec cascade_cancel(
  store :: StatifierPersistence.Storage.t(),
  metadata_match :: StatifierPersistence.Storage.Adapter.metadata(),
  opts :: keyword()
) :: {:ok, non_neg_integer()} | {:error, error()}

Cancels every run linked to parent_run_id - for one invocation, or for all of them - and every run linked to those, recursively (ADR-0008 decision 5).

Retains: nothing is deleted and every position is left byte-identical; each run simply takes the :cancelled terminal status through cancel/3.

Idempotent, and idempotent in the strong sense a crash needs. The walk descends into every child it finds, whatever that child's own status, and cancel/3 discards a run that is already terminal - so a cascade interrupted halfway through a deep tree is completed correctly by re-running it, and a cascade over a subtree that is already fully cancelled writes nothing at all.

There is no global transaction and there deliberately is none: each run's cancel is its own serialized write under its own run's exclusion (ADR-0004 decision 5), so a deep tree is O(subtree) writes. Cross-run locking is the only way to make it atomic, and this package does not have it and does not want it.

Termination rests on the run tree being acyclic, which it is by construction: a child's run id strictly extends its parent's (StatifierPersistence.Run.Linkage.child_run_id/3), so no run can be its own descendant. This is why no depth ceiling is needed (ADR-0008 decision 6).

That same fact is what makes the lock order safe, which is worth stating because this walk is the one place a cycle would be conceivable. It runs from inside the caller's own exclusion on every path that has one - the {:cancel_invoke, _} effect fires inside the exiting run's, and first_error's settlement fires it inside the PARENT's - and it only ever takes an exclusion on a run further down that same subtree. Nothing here holds a descendant's exclusion and then asks for an ancestor's: a child releases its own before answering its parent (Driver.maybe_answer_parent/3 runs after the drive returns), and the parent's door is stepped after the settlement's exclusion closes rather than inside it. So the wait-for relation between two connections embeds in the run tree, and an acyclic tree has no cycle to deadlock on. test/statifier_persistence/driver_fanout_test.exs pins the direction; its Ecto variant runs it against real Postgres advisory locks.

metadata_match is a StatifierPersistence.Run.Linkage containment map - Linkage.invocation_match/2 to cancel one invocation's subtree, Linkage.parent_match/1 for every child a parent has ever started. opts accepts serialization: only, threaded to every cancel/3 call the walk makes, exactly as cancel/3 itself accepts it.

@spec create(
  store :: StatifierPersistence.Storage.t(),
  run_id :: run_id(),
  machine :: Statifier.Machine.t(),
  opts :: [opt()]
) ::
  {:ok, StatifierPersistence.Run.t(), Statifier.MachineState.t()}
  | {:error, error()}

Creates a run: Statifier.Interpreter.initialize/2 (which cannot fail), then the shared persist tail - effects through the executor seam, :done/:budget_exhausted consumed into run status, quiescence asserted, the record inserted with its encoded position.

Create-exactly-once rests on the adapter's atomic :run_exists refusal (ADR-0004 decision 2), not on a pre-check here: creating an existing run_id returns {:error, :run_exists}.

A create whose initialize/2 exhausts its macrostep budget persists a :failed run with no position blob (there is no quiescent position to store - ADR-0004 decision 1) and then returns {:error, {:budget_exhausted, payload}}, so the caller sees both the durable state and the reason.

metadata: rides through to the inserted run record unchanged (ADR-0006 decision 1). Create is the only place it is set - step/5 and fail/4 carry the stored map forward and take no metadata: of their own - and an adapter that cannot store a non-empty map refuses here, before any effect is executed: {:error, :metadata_unsupported}.

@spec fail(
  store :: StatifierPersistence.Storage.t(),
  run_id :: run_id(),
  reason :: String.t(),
  opts :: keyword()
) ::
  {:ok, StatifierPersistence.Run.t()}
  | {:discarded, StatifierPersistence.Run.t()}
  | {:error, error()}

Abandons a run: the only host-driven terminal transition (ADR-0004 decision 6). No interpreter is involved - abandonment is a host decision about the run, not a chart transition - so the stored position is left untouched and only the record's status and failure reason change.

A terminal run is discarded, same as step/5: {:discarded, run}. reason is the short string stored as the run's failure - keep it a prefixed, console-readable reason, not an inspect dump.

opts accepts serialization: - the same {module, config} strategy create/4 and step/5 take, with the same default - and driver:.

driver: and a linked child (ADR-0008's outside-fail note)

A run failed here is failed from outside the interpreter, so nothing in this call steps a chart and nothing in it reaches the parent of a durable subchart child (ADR-0008 decision 2's linkage). Left there, a child a host abandons this way holds its parent's <invoke> :pending forever: every path that answers a parent hangs off a drive of the child, and an outside fail is the one terminal transition that has no drive.

driver: is that answer. Given a StatifierPersistence.Driver.t/0, a run that carried linkage and actually reached :failed here answers its parent with {:failed, reason: reason} - the ADR-0008 spelling, the same payload the automatic path builds from a run's stored failure - through StatifierPersistence.Driver.resolve_and_answer_parent/3, the same write site the stepped path uses. A fan-out child settles rather than answering, because that routing lives in StatifierPersistence.Driver.answer_parent/3 and both paths reach it.

The driver must be able to answer the parent: either its chart_resolver: resolves the parent's chart, or its machine already is the parent's chart. Its store is what the answer reads and writes through, so it is normally a driver over this same store.

Two boundaries this option does not cross. The answer happens after this run's own serialization section commits, not inside it - the same order create/3 and send_event/4 answer in, and the reason a nested exclusion is never taken here. And the answer's own outcome does not change this function's: a parent that has already cancelled the invocation, or that cannot be resolved, leaves {:ok, run} exactly as it is. What that window costs, and what closes it, is docs/adr/0008-durable-subchart-child-runs.md's note.

Without driver: nothing about this call changes, for a linked run or an unlinked one: no linkage is read and no parent is answered.

@spec inputs(store :: StatifierPersistence.Storage.t(), run_id :: run_id()) ::
  {:ok, [StatifierPersistence.Storage.input()]}
  | :not_supported
  | {:error, error()}

Lists run_id's input log, in the order the run's interpreter saw it (ADR-0010 decision 2).

Each entry carries its ordinal (seq, dense from zero), the public door it entered by, and the %Statifier.Event{} itself - equal to the one that was delivered, caller_context and all. An entry whose event is nil is the closed marker a host-declared cap wrote (decision 6); a reader mapping this log onto a replay refuses on it rather than replaying a run that never happened.

:not_supported for a store whose adapter keeps no log - which is not a failure, since nothing in this package refuses a run over it (decision 1). {:error, :run_not_found} for a run that does not exist, and {:ok, []} for one that has taken no input yet.

Read-only and outside the run's exclusion by design: this is a diagnostic read, and nothing in this package consumes it. The replay itself is StatifierUI.Trace.Replay.from_events/4's, under the mapping ADR-0010 decision 8 names and no code here builds.

@spec step(
  store :: StatifierPersistence.Storage.t(),
  run_id :: run_id(),
  machine :: Statifier.Machine.t(),
  event :: Statifier.Event.t() | event_builder(),
  opts :: [opt()]
) ::
  {:ok, StatifierPersistence.Run.t(), Statifier.MachineState.t()}
  | {:discarded, StatifierPersistence.Run.t()}
  | {:error, error()}

Delivers one external event to a run, in ADR-0004 decision 3's order (the moduledoc quotes it).

An event delivered to a terminal run returns {:discarded, run} from the run record alone, before any position decode. handle_event/2's {:error, :not_running} arm is the structural backstop for a run record whose :active status lies about a terminal stored position: it discards too, and repairs the record's status to :completed on the way out.

event may also be a event_builder/0 - a fun the loaded position is handed, for an event only the position can build or decline. A builder that declines discards the delivery through the same {:discarded, run} arm.