Document conversation capture and continuation contracts

types.go

@@ -87,10 +87,17 @@ const (
 type RunRequest struct {
 	// CaptureExchange requests an immutable snapshot of a completed run, even
 	// when its structural validation fails. Operational errors return no result.
+	// The snapshot is returned in RunResult.Exchange; see [Exchange] for its
+	// logical history contract. Prepare and ValidateRequest create no exchange.
+	// PrepareExecution retains this choice for its eventual RunPrepared call.
 	CaptureExchange bool
 	// ContinueFrom supplies captured history and implies capture of the new run.
 	// A non-nil zero-value exchange is invalid. Follow-up settings are selected
 	// normally and are not inherited from the exchange.
+	// Messages are assembled as captured history, rendered definition messages,
+	// then AppendedMessages. Prior templates and inputs are not rendered or read
+	// again. Continuation adds no history-size limit or truncation; upstream
+	// rejection follows the ordinary generation-error contract.
 	ContinueFrom *Exchange `json:"-" yaml:"-"`
 	// PromptID is the required prompt identifier. A namespace-scoped engine view
 	// qualifies a slashless caller value; otherwise it selects the exact