@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, exactly as fail/4 does.

@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).

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: only - the same {module, config} strategy create/4 and step/5 take, with the same default.

@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.