Harden backend contracts and documentation

types.go

@@ -101,8 +101,8 @@ type RunRequest struct {
 	// Vars supplies Go-template data for messages and the session ID. Nil and
 	// empty maps are equivalent.
 	Vars map[string]string
-	// Execution optionally overrides individual profile execution settings.
-	// Nil uses the selected profile over framework defaults.
+	// Execution optionally overrides individual execution settings. Nil uses
+	// the selected profile over its backend, when any, and framework defaults.
 	Execution *ExecutionTargetOverride
 	// Validation optionally replaces the prompt's complete output contract. It
 	// does not merge individual fields. Nil uses the prompt contract.
@@ -126,8 +126,8 @@ type PreparedRun struct {
 	// SelectedProfileID is the explicit request profile or prompt default that
 	// supplied execution settings.
 	SelectedProfileID string `json:"selected_profile_id"`
-	// SelectedBackendID is the selected profile's normalized backend ID. It is
-	// empty for an endpoint-only profile.
+	// SelectedBackendID equals EffectiveModelParams.BackendID. It is empty for
+	// an endpoint-only profile.
 	SelectedBackendID string `json:"selected_backend_id,omitempty"`
 	// EffectiveModelParams contains framework defaults overlaid by the selected
 	// backend, profile, and then request overrides. It excludes resolved API-key
@@ -184,8 +184,8 @@ type RunResult struct {
 	RenderedPromptHash string `json:"rendered_prompt_hash"`
 	// SelectedProfileID identifies the profile used for execution.
 	SelectedProfileID string `json:"selected_profile_id"`
-	// SelectedBackendID is the selected profile's normalized backend ID. It is
-	// empty for an endpoint-only profile.
+	// SelectedBackendID equals EffectiveModelParams.BackendID. It is empty for
+	// an endpoint-only profile.
 	SelectedBackendID string `json:"selected_backend_id,omitempty"`
 	// ModelName is the effective model name and equals
 	// EffectiveModelParams.Model.
@@ -268,7 +268,8 @@ type ArtifactReader interface {
 type ExecutionTarget struct {
 	// BackendID is the effective routing identity selected by the profile. It
 	// remains unchanged when a profile or request overrides Endpoint and is
-	// empty for endpoint-only profiles.
+	// empty for endpoint-only profiles. It is supplied to injected LLMClient
+	// implementations as part of the effective target.
 	BackendID string `json:"backend_id,omitempty"`
 	// Endpoint is the model-provider base URL.
 	Endpoint string `json:"endpoint"`
@@ -298,13 +299,15 @@ type ExecutionTarget struct {
 // ExecutionTargetOverride represents per-request runtime setting overrides and
 // has no stable JSON representation.
 //
-// Non-empty string fields replace profile values. Non-nil numeric pointers
-// replace profile values and preserve explicit zero. A non-empty ExtraParams
-// map replaces the complete profile map rather than merging keys. Empty string
-// fields, nil pointers, and a nil or empty ExtraParams map inherit the selected
-// profile over framework defaults.
+// Non-empty string fields replace profile and backend values. Non-nil numeric
+// pointers replace profile values and preserve explicit zero. A non-empty
+// ExtraParams map replaces the complete profile or backend map rather than
+// merging keys. Empty string fields, nil pointers, and a nil or empty
+// ExtraParams map inherit the selected profile over its backend, when any, and
+// framework defaults.
 type ExecutionTargetOverride struct {
-	// Endpoint replaces the profile endpoint when non-empty.
+	// Endpoint replaces the profile or backend endpoint when non-empty without
+	// changing the effective BackendID.
 	Endpoint string
 	// Model replaces the profile model when non-empty.
 	Model string
@@ -322,12 +325,13 @@ type ExecutionTargetOverride struct {
 	// ReasoningEffort replaces the profile value when non-blank. An empty value
 	// cannot clear a profile setting.
 	ReasoningEffort string
-	// APIKeyEnv replaces the profile environment-variable name when non-blank.
-	// A direct RunRequest.APIKey still takes precedence over environment lookup.
+	// APIKeyEnv replaces the profile or backend environment-variable name when
+	// non-blank. A direct RunRequest.APIKey still takes precedence over
+	// environment lookup.
 	APIKeyEnv string
-	// ExtraParams, when non-empty, replaces the profile map. Values must be
-	// JSON-compatible: nil, booleans, finite numbers, strings, arrays or slices,
-	// and maps with non-empty string keys. Cycles are invalid.
+	// ExtraParams, when non-empty, replaces the complete profile or backend map.
+	// Values must be JSON-compatible: nil, booleans, finite numbers, strings,
+	// arrays or slices, and maps with non-empty string keys. Cycles are invalid.
 	ExtraParams map[string]any
 }
 
@@ -346,7 +350,8 @@ type Profile struct {
 	// ID is the required non-blank profile identifier. WithProfiles trims it.
 	ID string
 	// BackendID optionally selects an engine backend. WithProfiles trims it.
-	// Backend membership is checked when a request selects the profile.
+	// Backend membership is checked when a request selects the profile; an
+	// unknown ID makes preparation fail with ErrProfileLoad.
 	BackendID string
 	// Endpoint is the model-provider base URL. It is required only when
 	// BackendID is blank and otherwise overrides the backend endpoint when
@@ -373,8 +378,8 @@ type Profile struct {
 	// supplies ExecutionTargetOverride.APIKeyEnv. It does not store a credential.
 	APIKeyRequired bool
 	// ExtraParams contains provider-specific JSON-compatible values. An empty
-	// map inherits framework defaults. WithProfiles validates and deeply copies
-	// it during NewEngine.
+	// map inherits backend request defaults, when any. WithProfiles validates
+	// and deeply copies it during NewEngine.
 	ExtraParams map[string]any
 }