Document and demonstrate execution controls

types.go

@@ -89,7 +89,10 @@ type RunRequest struct {
 	// applies it across preparation and execution; PrepareExecution retains it
 	// for RunPrepared, without counting preparation or idle time. Zero or a
 	// negative value selects no additional timeout. This is independent of the
-	// provider generation timeout. Cancellation remains cooperative.
+	// provider generation timeout and respects earlier parent cancellation or
+	// deadlines. Local timeout failures match ErrOperationTimeout and
+	// context.DeadlineExceeded. Cancellation remains cooperative; callbacks or
+	// 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,
@@ -182,7 +185,8 @@ type RunRequest struct {
 
 // PreparedRun contains prepared prompt execution state returned by
 // [Engine.Prepare] or [PreparedExecution.Details]. It does not include resolved
-// API key values, model output, validation results, or internal target presence
+// API key values. RunRequest.OnPrepared also supplies this detached value.
+// It does not include model output, validation results, or internal target presence
 // metadata. PreparedRun has a stable JSON representation.
 //
 // All maps, slices, pointers, and schema values are caller-owned copies. JSON