Reconcile reliable execution documentation

observations.go

@@ -10,7 +10,10 @@ import (
 
 // ExecutionObserver receives immutable metadata events synchronously. Callers
 // must synchronize shared state if separate runs use the same observer. A
-// callback must return for its run to progress; panics propagate to the caller.
+// callback must return for its run to progress; cancellation cannot interrupt
+// consumer code already in the callback. Do not block on work requiring the
+// same run's admission slot. Panics propagate without a promise of a terminal
+// event, and Promptkit keeps no asynchronous queue or durable history.
 type ExecutionObserver func(ExecutionEvent)
 
 // ExecutionEventKind identifies one point in an execution's lifecycle.
@@ -57,7 +60,11 @@ const (
 )
 
 // ObservedTokenCount distinguishes an omitted count from a reported zero.
-// Complete means every dispatched attempt reported the field.
+// On an attempt, Known and Complete are true together only for a reported
+// non-null integer. An aggregate Value sums known contributions; Known means
+// at least one attempt reported the field, and Complete means every dispatched
+// attempt did. With no dispatched attempts, aggregate zero is known and
+// complete. Unknown fields have Value zero.
 type ObservedTokenCount struct {
 	Value    int
 	Known    bool
@@ -78,6 +85,20 @@ type ObservedTokenUsage struct {
 // credentials, URLs, headers, or error objects. It has no stable JSON contract.
 // Identifiers themselves may be sensitive. Nonterminal aggregate counters are
 // zero; a terminal usage total must not be added to attempt usage.
+//
+// Generation is one for the initial generation and increases for repairs;
+// Attempt is one-based within each generation. Dispatched means Promptkit
+// invoked an HTTP attempt or injected Generate, not that a network packet was
+// sent or billable work occurred. A canceled capacity acquisition emits a
+// non-dispatched attempt with no usage. A retry-delay event describes the
+// completed or interrupted wait after the indexed failed attempt.
+//
+// GenerationDuration excludes capacity waiting, retry delay, and callback
+// work. Terminal phase durations sum measured phases; terminal Duration is
+// wall time and may also include preparation, validation, and callbacks.
+// Attempt success means generation succeeded, even if later validation rejects
+// its output. Failure is classified metadata; RetriesExhausted is a separate
+// flag and does not replace the underlying failure kind.
 type ExecutionEvent struct {
 	Kind               ExecutionEventKind
 	RunID              string