The :telemetry surface for this package's storage-phase seams (ADR-0009) - the single definition site for every [:statifier_persistence, ...] event name, and the one module in lib/ that calls :telemetry.execute/3.

docs/telemetry.md is the full contract: what each event answers, what it deliberately leaves to statifier-ex and to opentelemetry_ecto, and what opentelemetry_statifier does with it. This moduledoc is the reference table; that note is the reasoning.

events/0 returns every name below, built from the same literal-atom lists the emitters use, so the bridge can attach one handler per event name without hand-copying the list (ADR-0009 decision 8, ots-ADR-0003).

This module owns family two only. The interpreter's own family - [:statifier, :session, ...] with driver: :persistence - is emitted by calling Statifier.Telemetry directly from the stepper seam and is deliberately not wrapped here: a wrapper would be the second implementation st-ADR-0067 decision 2 exists to prevent.

Structural rules (ADR-0009 decisions 3, 5, 8, 9)

• The prefix is [:statifier_persistence, ...], fixed and not configurable. The bridge must name the events at compile time, and a per-host prefix would make its attach list depend on host configuration it cannot see.
• Measurements are numbers; metadata is everything else, integer indexes included - child_index is metadata, because an opaque index has no numeric meaning to average.
• Two spans: the step seam and the batch migration. This package owns an interval nobody else measures - lock, load, decode, identity-check, advance, execute effects, persist - and the upstream macrostep span nests inside it. A batch migration is the second (ADR-0017 decision 6): one call over every execution on a chart hash. Each opens with :start and closes with exactly one of :stop or :exception. span_ref is a fresh make_ref/0 per span, carried on both halves, and is the only pairing key (st-ADR-0040 decision 2). Everything else is a single point-in-time event.
• execution_id is the identity key, never scope; session_id rides only where a position has already been decoded and is explicitly nil otherwise.
• Emission is unconditional. There is no config knob and no sampling knob: :telemetry.execute/3 on an event with no handlers is a lookup and a return.
• Amendment discipline. Adding a measurement or a metadata key to an existing event is an amendment and is fine; renaming or removing one, renaming an event, or changing the :persistence driver atom is breaking and needs a new ADR.

The step seam

Brackets one serialized drive - create/4, step/5, fail/4 or cancel/3 inside StatifierPersistence.Executions's own serialized/5. Emitted on the calling process. The [:statifier, :session, :macrostep, ...] span opens and closes inside it.

entry is which public door was used: :create, :step, :done_invocation, :failed_invocation, :answer_parent, :fail, :cancel. outcome on the stop is :ok, :discarded or :error. [:statifier_persistence, :execution, :lock]'s duration is the wait for the per-execution exclusion, not the held time, and its outcome is :acquired or :unavailable. It is also emitted by StatifierPersistence.Executions.unpark/3, which takes the same exclusion and opens no step span.

invoke_id and child_count on the stop are nil on every ordinary drive and set on the entry: :answer_parent step a child takes on its parent's behalf, so the step span carrying a fan-out's whole assembled answer is recognisable as that one (the ADR-0009 sp-8wv amendment). child_count is nil for a single-child subchart.

selection on the stop says whether the event the step delivered selected a transition: :selected when it selected at least one and :none when it selected none, whether or not the position was created with trace: true. It is read off the returned position's Statifier.MachineState.last_selection/0, so it is set on every :ok step whose event ran an external round - :step, :done_invocation, :failed_invocation and :answer_parent - and nil on a :create, :fail or :cancel stop, which delivers no event, and on every :discarded or :error stop. :none does not say why: an event no transition names and one whose every guard was false read the same (the ADR-0009 sp-qrkx amendment).

:exception closes the span in place of :stop when anything inside the drive raises, throws or exits - a host executor, an event builder, an adapter or the serialization strategy - and the raise then reaches the caller unchanged, with its original stacktrace. Its keys are the ones :telemetry.span/3 puts on its own :exception event: the start half's metadata plus kind, reason and stacktrace. The raised term and its stacktrace can carry any value the failing code held - an event builder's is the decoded machine state, datamodel included - so both are narrowed before the event is emitted. reason is the exception's module for an :error (a raw Erlang error is normalized first, so a failed match reports MatchError), and for a :throw or :exit the thrown or exit atom, or :redacted for any other term. stacktrace keeps each frame's module and function, replaces an argument list by its arity, and keeps only :file and :line of the location. The caller's re-raise keeps the original reason and stacktrace.

:reentered is a point-in-time event inside the span: one per error.communication event the persist tail re-entered into the chart after an executor failure (ADR-0004 decision 4), emitted on the calling process after that re-entry was delivered and before the step's :stop, in delivery order. name is "error.communication", origin is the Statifier.Event.Cause.origin/0 tuple the event was raised with, and opts is the keyword list it was raised with ([sendid: id] for a failed <send>, [] otherwise). A host that folds the events it delivered to rebuild a position folds each of these after the event of the step that produced it, through Statifier.Interpreter.deliver_internal(machine_state, :platform, name, origin, opts), and reaches the persisted position. A failure whose re-entry was not delivered emits none. The event carries no span_ref: it pairs with its step by execution_id and by arriving between that step's :start and :stop.

The storage seam

callback is the StatifierPersistence.Storage.Adapter callback name, a closed vocabulary fixed by the behaviour. stage on a refusal is :position, :execution or :chart, and reason is :identity_mismatch or :unidentified_chart; only the two content hashes travel, never the Statifier.Machine.Identity structs the error term carries.

The execution lifecycle seam

driven_by on :terminated is :chart or :host - fail/4 and cancel/3 are the :host ones, and upstream emits nothing at all for them. :discarded's reason is the closed vocabulary :terminal_execution, :builder_declined, :position_terminal, and only the third sets repaired?: true.

:migrated fires once per successful StatifierPersistence.Executions.migrate/4, after its serialization section returns (ADR-0013 decision 5). It carries both content hashes under their own names, because a migration has two charts in hand, and dropped is the list of dropped state ids that were in the execution's configuration. A refused or parked migration emits nothing.

:unparked fires once per StatifierPersistence.Executions.unpark/3 that writes a :needs_migration execution back to :active, after its serialization section returns. content_hash is the chart the execution was parked on and goes on under. An unpark that writes nothing - of an :active execution, of a terminal one, or one refused - emits no :unparked.

The batch migration span (ADR-0017 decision 6)

Brackets one StatifierPersistence.Executions.migrate_batch/3 call, opened once its options are checked. Emitted on the calling process.

from and to are the plan's two content hashes. The stop's counts are the report's counts: would_migrate, would_refuse and skipped under the dry run; migrated, refused, parked and skipped under the apply. outcome is :ok or :error; on :error - a refusal of the whole batch - reason is that refusal and every count of the mode is 0, and on :ok it is nil. The exception's kind, reason and stacktrace are narrowed as the step span's are. The dry run and a whole-batch refusal open the span; a malformed option raises before it opens. Each execution the apply moves still emits its own [:statifier_persistence, :execution, :migrated] inside the span, and the dry run emits none.

The durable-subchart seam (ADR-0008)

content_hash on :started is the child's pinned hash (ADR-0008 decision 2). count on :cascade_cancelled is how many executions the sweep actually cancelled and retained is how many it found already terminal and left alone; both are legitimately 0.

:recorded fires once per fan-out child answer written under the parent's exclusion, and :settled once per settlement decision - decision is :answer or :not_yet - both from the settlement section (the ADR-0009 sp-8wv amendment). decision is the settlement's, not the parent's: a parked parent that refuses the assembled answer still reports :answer on :settled, and what its door answered is the delivery of the :answered that follows. :answered's outcome is the invocation's aggregate for a fan-out, :failed when any index failed, even though the parent's door is always done_invocation/5; and child_count and failed_count are nil on the single-child path, which is not an invocation with a width.

:answered's delivery is what the parent's door answered, a closed vocabulary: :delivered, :discarded (the parent had already left the invocation), :needs_migration (the parent is parked and refused the answer whole, ADR-0014 decision 2) or :error (any other error). The automatic answer returns the child's own result whatever the door answered, so :needs_migration here is how a host learns that an answer it must deliver again was refused. Two more values say the answer never reached a door: :parent_unfetched (the parent's own record did not fetch) and :parent_chart_unresolved (the driver's chart_resolver: did not return the parent's chart). On those two, outcome is the child's own and failed_count is nil, because no settlement ran.

Cardinality and disclosure

Every metadata key is bounded by the chart or by a closed vocabulary except execution_id (and parent_execution_id / child_execution_id), which is host-supplied and is a correlation id for a span or a log line, never a metric dimension, reason, which carries an arbitrary executor or adapter term on some events and must be narrowed before it becomes a dimension, and opts on :reentered, whose sendid is a <send>'s own id or one the interpreter generated for it: a value to fold, never a dimension.

Nothing host-opaque and nothing from the datamodel is ever on an event (ADR-0009 decision 7): not the chart_blob, the position_blob, the identity_blob, the ADR-0006 metadata map, the datamodel, an invoke's params, or a :done effect's donedata. metadata? on [:statifier_persistence, :execution, :created] is a boolean - whether a non-empty host map was supplied - and that is the whole of what this contract says about it.