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.
• The step seam is the one span. 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. It 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.

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

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

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, and reason, which carries an arbitrary executor or adapter term on some events and must be narrowed before it becomes 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.