promptkit/docs/internal/observation.md

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 currently supplies run IDs to the runner; attempt and lifecycle instrumentation is added at their owning boundaries.

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.

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 own usage presence, phase sums, event ordering, empty-run accounting, identity snapshots, and callback panic behavior. The generation coordinator owns attempt and retry-delay measurements once connected to this recorder.