Document appended request messages

types.go

@@ -125,10 +125,11 @@ type RunRequest struct {
 	Validation *OutputContract
 	// AppendedMessages are already-rendered messages appended after every prompt
 	// definition message. Promptkit neither templates nor resolves files in
-	// them, and preserves valid content exactly. Nil and empty slices are
-	// equivalent. Prepare, PrepareExecution, and Run validate and copy the
-	// messages before source or model work; malformed values return an error
-	// matching ErrInvalidRequest.
+	// them, and preserves valid content exactly. Roles are trimmed and
+	// lowercased, then must be [RoleDeveloper], [RoleSystem], [RoleUser], or
+	// [RoleAssistant]. Nil and empty slices are equivalent. Prepare,
+	// PrepareExecution, and Run validate and copy the messages before source or
+	// model work; malformed values return an error matching ErrInvalidRequest.
 	AppendedMessages []RenderedMessage
 }
 
@@ -632,13 +633,15 @@ type RenderedPrompt struct {
 	// SessionID is the optional effective direct or rendered session
 	// identifier supplied to the model client.
 	SessionID string `json:"session_id,omitempty"`
-	// Messages contains rendered messages in definition order.
+	// Messages contains the frozen effective messages: definition messages in
+	// their rendered order followed by any RunRequest.AppendedMessages.
 	Messages []RenderedMessage `json:"messages"`
 }
 
 // RenderedMessage is a prepared, provider-bound text chat message and has a
-// stable JSON representation. Its role must be one of [RoleDeveloper],
-// [RoleSystem], [RoleUser], or [RoleAssistant].
+// stable JSON representation. At a request boundary its role is trimmed and
+// lowercased, then must be one of [RoleDeveloper], [RoleSystem], [RoleUser],
+// or [RoleAssistant].
 type RenderedMessage struct {
 	// Role is the provider-bound chat role.
 	Role string `json:"role"`