Harden backend contracts and documentation

docs/internal/llm.md

@@ -20,6 +20,11 @@ orchestration. `OpenAICompatibleClient` is the built-in implementation. It
 uses internal domain values for rendered prompts, execution targets,
 structured output, responses, and token usage.
 
+The runner supplies a fully resolved target after applying backend, profile,
+and request precedence. The client uses its endpoint, credential metadata,
+generation fields, and extra parameters. `BackendID` remains routing metadata
+for the generation boundary and is not mapped into the provider payload.
+
 Construction validates the configured base URL and clones any supplied
 `http.Client` so Promptkit can apply its timeout default without mutating the
 caller's client. Generation then:
@@ -51,5 +56,7 @@ The
 [OpenAI-compatible client tests](../../internal/llm/openai_compatible_client_test.go)
 own configuration, client cloning, deterministic deadline precedence,
 authentication, request and response mapping, malformed data, error identity,
-cancellation, and response-body suppression. They use local test servers and
-test transports; the default suite makes no live or paid provider requests.
+cancellation, and response-body suppression. The root transport contract test
+also verifies that resolved backend settings reach this client without
+serializing backend identity. All use local test servers or test transports;
+the default suite makes no live or paid provider requests.

docs/internal/overview.md

@@ -11,21 +11,21 @@ contributor workflow and validation.
 
 | Component | Implemented responsibility | References |
 | --- | --- | --- |
-| Root `promptkit` package | Provides the supported engine facade, source and injection options, public request and result values, built-in profile construction, extension interfaces, value conversion, redacted formatting, and public error mapping. | [Package GoDoc](../../doc.go), [engine assembly](../../engine.go) |
+| Root `promptkit` package | Provides the supported engine facade, source, backend-registration, and injection options, public request and result values, profile construction, extension interfaces, value conversion, redacted formatting, and public error mapping. | [Package GoDoc](../../doc.go), [backend API](../../backends.go), [engine assembly](../../engine.go) |
 | `examples/go-library/prepare` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, and `Prepare`. It is not a public library package. | [Example program](../../examples/go-library/prepare/main.go) |
 | `examples/go-library/run` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, an injected deterministic model client, and `Run`. It is not a public library package. | [Example program](../../examples/go-library/run/main.go) |
-| `internal/backend` | Validates and defensively copies immutable OpenAI-compatible backend definitions, supplies the built-in OpenRouter definition, and owns the shared reserved request-field rule. | [Backend registry](../../internal/backend/registry.go) |
+| `internal/backend` | Constructs each engine's immutable registry from the built-in OpenRouter definition and consumer additions, validates and defensively copies definitions, and owns the shared reserved request-field rule. | [Backend registry](../../internal/backend/registry.go) |
 | `internal/domain` | Defines internal framework values for requests, artifacts, prompt definitions, profiles, execution targets, rendering, generation, and validation. | [Domain declarations](../../internal/domain/domain.go) |
 | `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) |
 | `internal/filecatalog` | Provides deterministic YAML discovery and path helpers for operating-system filesystems and `fs.FS` sources. | [File catalog](../../internal/filecatalog/catalog.go) |
 | `internal/promptdef` | Loads strictly decoded, validated prompt definitions from filesystem and `fs.FS` sources, including version selection and contained file-backed message content. | [Framework formats](../formats.md), [prompt-definition repository](../../internal/promptdef/filesystem_repository.go) |
-| `internal/profile` | Loads strictly decoded, validated execution profiles from filesystem and `fs.FS` sources and composes repositories with error-preserving fallback. | [Framework formats](../formats.md), [profile repositories](../../internal/profile/filesystem_repository.go) |
-| `internal/profile/builtin` | Embeds the built-in execution profile catalog and combines it with an optional primary repository. | [Built-in catalog](../formats.md#built-in-profile-catalog), [repository](../../internal/profile/builtin/repository.go) |
+| `internal/profile` | Loads strictly decoded, validated execution profiles, including backend selection, from filesystem and `fs.FS` sources and composes repositories with error-preserving fallback. | [Framework formats](../formats.md), [profile repositories](../../internal/profile/filesystem_repository.go) |
+| `internal/profile/builtin` | Embeds the built-in profile catalog, whose entries select OpenRouter, and combines it with an optional primary repository. | [Built-in catalog](../formats.md#built-in-profile-catalog), [repository](../../internal/profile/builtin/repository.go) |
 | `internal/prompt` | Renders prompt messages from Go templates with artifact, variable, session, and cache-control data. | [Go-template renderer](../../internal/prompt/go_renderer.go) |
 | `internal/artifact` | Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes. | [Internal sources and validation](sources.md) |
 | `internal/validate` | Validates basic, JSON, and JSON Schema output using operating-system filesystem or `fs.FS` schema sources. | [Framework formats](../formats.md#schemas), [internal sources and validation](sources.md) |
-| `internal/llm` | Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests, response decoding, authentication, and deadline handling. | [Internal model client](llm.md) |
-| `internal/usecase` | Coordinates preparation and execution across internal sources, rendering, artifact loading, generation, validation, and optional repair. | [Internal runner](runner.md) |
+| `internal/llm` | Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests from resolved execution targets, including response decoding, authentication, and deadline handling. | [Internal model client](llm.md) |
+| `internal/usecase` | Resolves backend, profile, and request settings and coordinates preparation and execution across internal sources, rendering, artifact loading, generation, validation, and optional repair. | [Internal runner](runner.md) |
 
 The root package assembles these internal components without exposing their
 representations. Consumers depend only on the root facade.

docs/internal/runner.md

@@ -18,10 +18,11 @@ and override semantics consumed by the runner.
 
 `Runner` coordinates narrow internal interfaces for prompt definitions,
 profiles, backend resolution, artifacts, rendering, model generation, and
-validation. The root engine supplies an immutable built-in backend registry.
-Schema documents are loaded through the validator's optional schema-loader
-interface. An output repairer can be injected internally, but the ordinary
-runner constructor does not enable one.
+validation. The root engine supplies one immutable registry containing the
+built-in backend and validated consumer additions. Schema documents are loaded
+through the validator's optional schema-loader interface. An output repairer
+can be injected internally, but the ordinary runner constructor does not
+enable one.
 
 Each invocation carries its state in request, prepared-run, and result values.
 The runner has no durable run or session store.
@@ -53,6 +54,10 @@ apply in that order. A profile requiring a direct key clears an inherited
 backend environment name unless the request supplies its own name. Secret
 values remain excluded from serialized metadata.
 
+The registry is read-only after engine construction. Concurrent `Prepare` and
+`Run` calls resolve independent defensive backend values and keep all
+invocation state local.
+
 ## Run Flow
 
 `Run` calls `Prepare` rather than maintaining a second preparation path. It

docs/internal/sources.md

@@ -36,7 +36,8 @@ profile selects `openrouter` and inherits its endpoint and credential
 environment-variable name from the built-in backend registry rather than
 repeating those values. Profile behavior is owned by the
 [profile repository tests](../../internal/profile/repository_test.go), while
-catalog completeness, backend-selection invariant, duplicate IDs, and overlay behavior are owned by the
+catalog completeness, the backend-selection invariant, duplicate IDs, and
+overlay behavior are owned by the
 [built-in repository tests](../../internal/profile/builtin/repository_test.go).
 
 ## Ordinary Artifacts