Document conversation capture and continuation contracts

exchange.go

@@ -7,17 +7,28 @@ const exchangeString = "promptkit.Exchange{opaque}"
 // Exchange is an immutable, reusable in-process snapshot of a completed
 // conversation. It is not a persistence or restart format. Different engines
 // can continue it, and independent branches do not alter one another.
+//
+// History preserves the effective request's message content, roles, and cache
+// metadata, followed by the exact final [RunResult.RawOutput] as an assistant
+// message. Intermediate structural-repair candidates and corrective instructions
+// are excluded. A continuation extends that logical history according to
+// [RunRequest.ContinueFrom], without changing its source exchange.
 type Exchange struct{ internal *domain.Exchange }
 
 // ExchangeDetails contains a detached copy of an exchange's logical history.
 type ExchangeDetails struct {
-	RunID       string            `json:"run_id"`
+	// RunID identifies the execution that produced this exchange.
+	RunID string `json:"run_id"`
+	// ParentRunID identifies the immediate source execution, or is empty.
 	ParentRunID string            `json:"parent_run_id,omitempty"`
 	Messages    []RenderedMessage `json:"messages"`
 }
 
 // Details returns detached history, or zero details for a nil or empty handle.
 // Messages include caller and model content and require appropriate handling.
+// Inspection uses only retained state, without rendering, filesystem reads, or
+// provider calls. Mutating returned messages or cache metadata cannot affect
+// this exchange, another branch, or subsequent Details calls.
 func (e *Exchange) Details() ExchangeDetails {
 	if e == nil || e.internal == nil {
 		return ExchangeDetails{}