Clarify prepared notification timing and context

types.go

@@ -95,13 +95,18 @@ type RunRequest struct {
 	// collaborators that ignore context cannot be forcibly interrupted.
 	OperationTimeout time.Duration `json:"-" yaml:"-"`
 	// OnPrepared synchronously receives detached, credential-redacted details of
-	// the logical request after preparation and admission, before generation,
-	// if execution reaches that point. Admission remains held, and callback time
-	// consumes OperationTimeout. The callback owns the delivered mutable values;
-	// its closure is shared and must synchronize any shared state. It has no
-	// error return, and a panic propagates after resource cleanup. Prepare and
-	// ValidateRequest do not invoke it; PrepareExecution retains the selected
-	// function for RunPrepared and Discard releases it.
+	// the logical request after preparation and admission, before the first
+	// generation, at most once per logical execution if it reaches that point.
+	// Transient retries and structural repair do not repeat the notification.
+	// Its context is the operation-scoped context, subject to OperationTimeout
+	// and parent cancellation/deadlines. In [Engine.Coordinate], this differs
+	// from the parent context passed to the next-turn callback.
+	// Admission remains held, and callback time consumes OperationTimeout. The
+	// callback owns the delivered mutable values; its closure is shared and must
+	// synchronize any shared state. It has no error return, and a panic propagates
+	// after resource cleanup. Prepare and ValidateRequest do not invoke it;
+	// PrepareExecution retains the selected function for RunPrepared and Discard
+	// releases it.
 	OnPrepared func(context.Context, PreparedRun) `json:"-" yaml:"-"`
 	// CaptureExchange requests an immutable snapshot of a completed run, even
 	// when its structural validation fails. Operational errors return no result.