# Internal Execution Observation

`internal/observation` owns one invocation's run ID, presence-aware token
aggregation, measured phase totals, and synchronous metadata event delivery.
Its event values and callback type live in `internal/domain` so internal
requests can carry them without depending on the recorder package. The
recorder supplies run IDs to the runner and receives attempt and
retry-delay measurements from the generation coordinator. Ordinary `Run`
lifecycle instrumentation spans the facade and runner boundaries.
Prepared execution starts only after its private payload is atomically claimed;
the facade receives that invocation's recorder privately and emits the terminal
event after public error mapping. Failed claims and preparation emit nothing.

A recorder keeps only counters, resolved identity fields, and the selected
callback. It has no global history, queue, goroutine, or mutex held across a
callback. The caller supplies normalized failure metadata; the recorder never
parses an error string or receives provider bodies, credentials, headers, or
other content. Events are values with no mutable containers. Callback panics
propagate to the caller.
Per-operation callbacks are ordered and synchronous; different operations may
invoke the same callback concurrently. The recorder marks each measured phase's
end before delivery, so callback work does not inflate provider duration.
Terminal phase durations sum measured phases, while wall duration may also
include preparation, validation, and callbacks. Panics do not promise a
terminal event.

Attempt usage is known when its explicit presence bit is true. For legacy
injected clients without presence metadata, nonzero counts are known and
zeros are unknown. Aggregate values sum known contributions; `Known` means
at least one reported value, while `Complete` means every dispatched attempt
reported the field. Zero dispatched attempts produce known, complete zero
totals. Non-dispatched acquisitions contribute capacity wait but no usage or
generation duration. Terminal totals count dispatched attempts, transient
attempts above the first in a generation, and repair generations with at least
one dispatch. A terminal event is an aggregate and must not be added to its
attempt events.

The [recorder tests](../../internal/observation/recorder_test.go) own usage
presence, phase sums, event ordering, empty-run accounting, identity snapshots,
and callback panic behavior. The [generation coordinator](generation.md) owns
attempt and retry-delay measurements and emits their completion events after
releasing active permits.