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

Cancels an execution: 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. An execution that is already terminal - cancelled by an earlier, interrupted cascade included - is discarded with {:discarded, execution}, which is what makes re-running a cascade over an already-cancelled subtree a no-op. A :needs_migration execution is cancelled exactly as an :active one is, so a cascading cancel reaches a parked child (ADR-0014 decision 2).

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 execution linked to parent_execution_id - for one invocation, or for all of them - and every execution linked to those, recursively (ADR-0008 decision 5).

Retains: nothing is deleted and every position is left byte-identical; each execution 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 an execution 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 execution's cancel is its own serialized write under its own execution's exclusion (ADR-0004 decision 5), so a deep tree is O(subtree) writes. Cross-execution 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 execution tree being acyclic, which it is by construction: a child's execution id strictly extends its parent's (StatifierPersistence.Execution.Linkage.child_execution_id/3), so no execution 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 execution's, and first_error's settlement fires it inside the PARENT's - and it only ever takes an exclusion on an execution 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 execution 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.Execution.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(),
  execution_id :: execution_id(),
  machine :: Statifier.Machine.t(),
  opts :: [create_opt()]
) ::
  {:ok, StatifierPersistence.Execution.t(), Statifier.MachineState.t()}
  | {:error, error()}

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

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

A create whose initialize/2 exhausts its macrostep budget persists a :failed execution 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 execution 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}.

A chart a retirement has tombstoned refuses here too, in the same place and for the same reason: {:error, {:chart_retired, info}} (ADR-0012 decision 6). An execution created on a retired hash would persist and then be unresumable, because the rebuild reads the chart back through StatifierPersistence.Storage.fetch_chart/2 and gets the retired arm. A retirement refuses for as long as anything pins the hash, so a create after one is the single way an execution comes to stand on a tombstone.

@spec executions_on(
  store :: StatifierPersistence.Storage.t(),
  content_hash :: StatifierPersistence.Storage.Adapter.content_hash()
) ::
  {:ok, StatifierPersistence.Storage.Adapter.execution_counts()}
  | {:error, error()}

Counts the executions on content_hash, per stored arm (ADR-0012 decision 3).

Answers %{active: n, needs_migration: n, completed: n, failed: n, cancelled: n, children: n} - every key present for every hash, and zeros for a hash this store has never seen. The five arm keys are the stored statuses and nothing else: terminal is a fold this record's decision 2 names in prose and never stores, so a caller that wants it adds completed, failed and cancelled itself. needs_migration counts the parked executions on the hash (ADR-0014 decision 4): they are not terminal, and they pin the chart as active ones do, so this key is how a host finds the executions a migration left behind.

children counts the durable-child linkage pins on the hash whose parent execution is :active or :needs_migration, whatever arm the child itself is in (ADR-0012 decision 1, as ADR-0014 decision 4 reads it). It counts pins and not rows, so it is a different population from the five arm keys and can be non-zero for a hash carrying no execution row of its own.

{:error, :content_hash_query_unsupported} for a store whose adapter does not answer the query, without calling the adapter at all.

This is a read of a chart's traffic and not a retirability test (ADR-0012's consequences): the three terminal arms it reports never block a retirement, and the position rows and host pin sources that do are not in it. A host sweeping for retirable charts asks this to find candidates and asks the retirement itself whether a candidate can go.

Read-only, and outside any execution's exclusion by design: it takes no lock and counts what is committed at the moment it runs.

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

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

A terminal execution is discarded, same as step/5: {:discarded, execution}. A :needs_migration execution is failed exactly as an :active one is: giving up on a parked execution is a host decision about it, not an event for its chart (ADR-0014 decision 2). reason is the short string stored as the execution'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)

An execution 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, an execution 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 an execution'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 execution'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, execution} 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 execution or an unlinked one: no linkage is read and no parent is answered.

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

Lists execution_id's input log, in the order the execution'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 an execution that never happened.

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

Read-only and outside the execution'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 migrate(
  store :: StatifierPersistence.Storage.t(),
  execution_id :: execution_id(),
  plan :: StatifierPersistence.Migration.Plan.t(),
  opts :: keyword()
) ::
  {:ok, StatifierPersistence.Execution.t(), migrated()}
  | {:parked, {:migration_refused, [migration_finding()]}}
  | {:error, migrate_error()}

Moves one execution from the chart it is pinned to onto another, whole or not at all (ADR-0013; the park is ADR-0014's).

plan is a StatifierPersistence.Migration.Plan. The two compiled machines arrive in opts, because a stored chart is opaque to this package (ADR-0013 decision 9):

• from_machine: (required) - the machine whose content hash is the plan's from; the position is loaded with it, through the identity guard, exactly as a step loads it.
• to_machine: (required) - the machine whose content hash is the plan's to. The host saves this chart with StatifierPersistence.Storage.save_chart/3 before it migrates, as it does before create/4 (decision 4).
• pin_sources: - the host's list of StatifierPersistence.PinSource modules, default [], asked for pending timers (decision 6). They arrive here in opts, where retire_chart/4 takes the same list as a positional argument.
• on_failure: - :refuse (the default) or :park (decision 4).
• serialization: - the {module, config} strategy every entry point takes, with the same default. Its with_execution/3 is called directly; a migration is not a step and takes no step span (decisions 4 and 5).

Timers

This package stores no timer and changes none: a pending delayed send stays in the host's queue with its deadline, and a plan that maps the state around it keeps it (keep_mapped). The counters cross verbatim, so a send id or a timer ordinal the migrated execution mints cannot collide with one a surviving timer holds (decisions 2 and 6).

A state could own a timer when, in the from chart, a <send> with a delay or a delayexpr appears in its onentry, its onexit, a transition it owns (its <initial> and a history default included) or the <finalize> of one of its <invoke>s, nested <if> and <foreach> bodies included. The rule is static because a pin source answers counts, which name no state:

• a plan that maps every such state needs no pin source, and none is asked;
• otherwise, with no pin_sources:, the migration is refused with {:no_pin_source, states} before the execution is read - it fails closed, never blind to timers;
• otherwise the sources are asked, through StatifierPersistence.PinSource.collect/3, with the plan's from hash and the one execution's id in :execution_ids. A source that does not answer refuses with {:pin_source_failed, {module, reason}}; a non-zero count refuses with a {:pending_timers, states, source_counts} finding when the plan leaves any such state unmapped, and never when it drops them all.

Children

A migration moves one execution and rewrites nothing in any durable child of it: not the child's row, its linkage or its position (decision 7). A child's linkage pins the child's own chart, and execution metadata is write-once. A live child reaches its parent by its invocation id alone, and the invocation ids in the parent's active invocations cross unchanged: every active invocation maps to a key of the to chart, through the plan's invocations or by the same-ordinal default, and that key names the <invoke> element the invocation was started from, or the migration is refused with an invocation finding (decision 3; ADR-0013's 2026-09-23 Amendment, finding 1). So the parent's own position answers whether its children still resolve; no child is read and no child's lock is taken. Under on_failure: :park a refusal parks the parent only.

Migrating a child together with its linkage pin, or a tree of executions together, is migrate_tree/4's (ADR-0015).

What it does

In this order, and every check and the whole transform come before the one write (decision 4): the plan is validated against the two machines (decision 3, static); a tombstoned to hash is refused; a plan that leaves unmapped or drops a state that could own a timer is refused when no pin source is supplied; then, under the execution's serialization, the execution is read and refused if terminal or stored on another chart than the plan's from; the pin sources are asked when the plan puts a state that could own a timer at risk; its position is loaded with the from machine through StatifierPersistence.Storage.load_execution_position/3; Statifier.Position.export/1 translates it; the export is checked against the plan and transformed (decisions 2 and 3); and Statifier.Position.import/2 rebuilds it on the to machine. Then one StatifierPersistence.Storage.update_execution/5 writes the imported position back at :active, which replaces the identity, the content hash and the position blob together, and nothing that can fail follows it (decisions 4 and 9). The counters cross verbatim; the metadata, the input log and any durable child are not touched (decisions 2 and 7).

Afterwards a load with the to machine passes the identity guard and a load with the from machine is refused with its identity_mismatch arm. One [:statifier_persistence, :execution, :migrated] event is emitted after the serialization section returns, and nothing is stored as a trace (decision 5).

What it answers

• {:ok, execution, migrated} - the execution, now :active on the to hash, and migrated/0.
• {:error, reason} - migrate_error/0. Nothing is written.
• {:parked, {:migration_refused, findings}} - under on_failure: :park only, when the validation against the execution refused. The one write is the execution's status, :needs_migration, with a nil failure; its position, content hash, identity, metadata and input log stay as they were, on the from chart (ADR-0014 decision 1). Every other refusal writes nothing under either value: a static one, a tombstoned to hash, a missing pin source, a lock that could not be taken, a terminal execution, one stored on another chart, and a pin source that did not answer. The missing pin source and the source that did not answer are ADR-0013's 2026-09-23 Amendment to decisions 3 and 4.

A :needs_migration execution is migrated as an :active one is, and a successful migration writes it back at :active (ADR-0014 decision 3).

Nothing in this package calls this function: saving a chart, creating an execution and stepping one never migrate anything (decision 9).

@spec migrate_tree(
  store :: StatifierPersistence.Storage.t(),
  root_execution_id :: execution_id(),
  plans :: %{
    required(execution_id()) => StatifierPersistence.Migration.Plan.t()
  },
  opts :: keyword()
) ::
  {:ok, [{StatifierPersistence.Execution.t(), migrated()}]}
  | {:parked, {:tree_refused, %{required(execution_id()) => tree_refusal()}}}
  | {:error, migrate_tree_error()}

Moves a tree of executions - a parent and the durable children it invoked - onto newer charts, whole or not at all (ADR-0015; the write of a child's linkage pin is ADR-0008's 2026-09-23 Amendment).

plans maps an execution id to one StatifierPersistence.Migration.Plan, one per node the host moves; the same plan may serve several nodes. A node absent from plans is left untouched - its row, its linkage and its position - and, when it is live, must still resolve against its parent as that parent will stand after the move (decision 1). A child moved on its own is moved with the child as the root.

Options

• machines: (required) - a map from content hash to compiled machine, holding the from and to machine of every plan. A plan whose machine is missing is refused with {:machine_missing, hash}.
• pin_sources:, on_failure: and serialization: - migrate/4's, with its meanings and defaults.

What it does

Nothing is read or written for an adapter that does not declare the unit: that is {:error, :tree_migration_unsupported} (decision 3). Then every node's plan is checked against its two machines exactly as migrate/4 checks its one plan - the static validation, a tombstoned to hash, a missing pin source - before any execution is read.

The tree is read through the linkage, as cascade_cancel/3 reads it, through every child whatever its status (decision 2), and an id in plans outside it is refused. The exclusion of every named node is taken through the serialization strategy's with_execution/3, each ancestor before its descendants and siblings in ascending id, and held until the write has returned; a node absent from plans is read and never locked. The tree is read again under the exclusions, and the named nodes are checked against that second read.

Every named node is then validated as migrate/4 validates its one execution - the same functions, children first and the root last: refused when terminal or stored on another chart than its plan's from, its pin sources asked with its plan's from hash and its own id, its position loaded through the identity guard, checked and transformed. Every live node absent from plans whose parent is named is checked against the parent's transformed position. Every refusal from every node is collected before anything is written.

The write is one call to StatifierPersistence.Storage.Adapter.write_tree_migration/2 through StatifierPersistence.Storage.write_tree_migration/2: one transaction on a database, one atomic state transition on an adapter without one, so every write in it lands or none does (decision 3). It carries one re-pin per named node, children first: the record migrate/4's one write would carry, and for a node with a linkage its pin's new content_hash. Nothing that can fail follows it.

What it answers

• {:ok, moved} - moved is one {execution, migrated} pair per named node, children first and the root last, each as migrate/4 answers for one node. One [:statifier_persistence, :execution, :migrated] event per pair follows, in that order, once every exclusion is released (decision 5).
• {:error, reason} - migrate_tree_error/0. No node was written.
• {:parked, {:tree_refused, refusals}} - under on_failure: :park only, when every refusal is one migrate/4 parks for its own node ({:migration_refused, findings}) or the resolve rule's {:child_unresolved, _, _}. Then every named node - including one whose own plan would have applied - is written :needs_migration with a nil failure, in the same one unit, and nothing else of it changes; no node absent from plans is parked (decision 4). Any other refusal parks nothing.

A refused or parked tree emits no event. Nothing in this package calls this function: saving, publishing and stepping never migrate anything.

@spec retire_chart(
  store :: StatifierPersistence.Storage.t(),
  content_hash :: StatifierPersistence.Storage.Adapter.content_hash(),
  pin_sources :: [module()],
  opts :: keyword()
) :: {:ok, retired_chart()} | {:error, error()}

Retires the chart on content_hash, or refuses with every count (ADR-0012 decisions 5 and 6).

The host-facing door of the two decision 5 names. This one owns everything that reaches outside the package - the pin sources a host registered, and the refusal for a source that cannot answer - and StatifierPersistence.Storage.retire_chart/3 beneath it owns this package's own tables, the counts taken inside the transaction, and the tombstone write.

pin_sources is the host's list of StatifierPersistence.PinSource modules, [] for a host with none. Each is asked through StatifierPersistence.PinSource.collect/3, with a context carrying the ids of the :active executions on the hash, because a source such as a timer queue knows executions and never knows content hashes (decision 4). A :needs_migration execution is not in that list (ADR-0014 decision 4): it already refuses the retirement through its own count.

What refuses

A non-zero count anywhere in decision 1's blocking set, as ADR-0014 decision 4 reads it - an :active or :needs_migration execution row on the hash, a durable-child linkage pin naming it whose parent is :active or :needs_migration, a position row on it, or any source's non-zero count - answers {:error, {:pinned, counts}} and writes nothing. A parked execution pins its chart as an :active one does: it is not terminal, and unpark/3 puts it back to :active on the chart it was already pinned to. The refusal carries every count it knows, this package's own under its own name and each source's under that source's module name, so a host learns everything holding the chart in one answer rather than one refusal per retry. The three terminal execution arms are in that map and never cause it: a terminal row never goes away, and counting one as a pin would make a chart permanently unretirable the first time anything on it finished.

A store that cannot answer the drained query refuses at open with {:error, :content_hash_query_unsupported}, and a store that cannot carry a tombstone at all with {:error, :chart_retirement_unsupported}

• both before any source is asked and before anything is counted. {:error, :chart_not_found} is a hash never stored, and {:error, {:chart_retired, info}} a hash already retired: a second retirement is the retired arm, never a second tombstone.

A source that could not answer refuses on its own, and carries no counts

{:error, {:pin_source_failed, {module, reason}}}, where reason is StatifierPersistence.PinSource.reason/0: {:raised, exception}, {:thrown, value}, {:exited, reason} or {:invalid_return, value}. It is a different arm from {:pinned, counts} and it carries no count map at all, deliberately: the walk stops at the first source that could not answer, so no complete count exists to report, and a refusal shaped like a count would let a host read a partial one as the whole. "The source could not answer" and "the source answered zero" are different facts (decision 4), and so are "here is everything holding this chart" and "here is some of it".

Options

• retired_by: (required) - the opaque host string recorded on the row as who asked. This package does not interpret it.
• now: - the DateTime.t/0 written as retired_at. Defaults to DateTime.utc_now/0. There is no clock here: deciding when a chart should be retired is host policy, and nothing in this package retires on its own or on a schedule (decision 7).

Afterwards

The row and its content hash are kept and both blobs are nil. StatifierPersistence.Storage.fetch_chart/2 on that hash answers the retired arm rather than :chart_not_found, and StatifierPersistence.Storage.save_chart/3 refuses it rather than reviving the row. Retirement is irreversible through the public surface: a host that retires a hash it still wanted re-authors the document and saves the result under its new hash.

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

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

An event delivered to a terminal execution returns {:discarded, execution} from the execution record alone, before any position decode. handle_event/2's {:error, :not_running} arm is the structural backstop for an execution 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.

An event delivered to a :needs_migration execution is refused whole with {:error, {:needs_migration, execution}}, also from the execution record alone and before any position decode: nothing is appended to the input log, no effect is executed and nothing is written (ADR-0014 decision 2).

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, execution} arm.

@spec unpark(
  store :: StatifierPersistence.Storage.t(),
  execution_id :: execution_id(),
  opts :: keyword()
) ::
  {:ok, StatifierPersistence.Execution.t()}
  | {:discarded, StatifierPersistence.Execution.t()}
  | {:error, error()}

Puts a :needs_migration execution back to :active on the chart it was already pinned to (ADR-0014 decision 3): the way out of the arm for a host that decides the execution should go on unmigrated.

The status is the only thing written. The execution goes on at the position it was parked at, under the content hash it already carried, with its blobs, metadata and input log as they were; the write is StatifierPersistence.Storage.update_execution_status/4's, which carries every other stored field forward. Nothing is replayed: a delivery that was refused while the execution was parked is delivered again by the host or not at all.

An :active execution answers {:ok, execution} and nothing is written, so re-running an interrupted unpark changes nothing. A terminal execution answers {:discarded, execution}, as fail/4 and cancel/3 do.

opts accepts serialization: only, with cancel/3's default. The call runs inside the execution's serialization strategy and opens no step span. It emits [:statifier_persistence, :execution, :lock] for the wait on that exclusion, as the step seam does, and [:statifier_persistence, :execution, :unparked] once the section has returned, only when it wrote :active; an :active, terminal or refused execution emits no :unparked (ADR-0014's telemetry amendment).