# Configuration Internals This guide explains the maintained configuration boundary and its composition-root handoff. [Configuration](../config.md) owns source selection, syntax, fields, defaults, and selectable modules; [CLI Reference](../cli.md) owns invocation. [Architecture](../policy/architecture.md#configuration-and-provenance) defines ownership. Do not infer operator contracts from private helper choices here. ## Owners And Handoffs | Owner | Responsibility | | --- | --- | | [core/config definition](../../internal/core/config/load.go) | Typed application document, native PromptKit configuration rules, application resolution/validation. | | [CLI loaders](../../internal/cli/configkit_load.go) | Main-source selection, native underlays, invocation-local result/engine reuse. | | [LoadedConfig](../../internal/core/config/loaded_config.go) | Retain the original result and derive independently owned runtime pipeline configuration. | | [Config.Resolve](../../internal/core/config/effective_config.go) | Resolve a selected pipeline against the supplied catalog. | | [preflight](../../internal/preflight/preflight.go) | Check known native resources from resolved composition and supplied engine. | | Pipeline preparation | Construct typed execution collaborators from resolved, materialized inputs; see [Pipeline Internals](pipeline.md). | The production flow keeps one application-owned `*configkit.Result[config.Document]`. That result feeds runtime conversion, whole-app/focused inspection, and `promptkit.NewFromConfig`. Rendered YAML is an operator view, not an interchange format for constructing the engine. ## Definition And Application Meaning `Document` contains native `promptkit.Settings` at its PromptKit field. `Definition` composes application defaults, version policy, sensitivity, identified step lists, resolution, and validation with `promptkit.Configure`. Native resource rules therefore participate in the same load rather than being validated by a separate application parser. Application callbacks normalize pipeline identifiers and operational paths while retaining presence/source history. The per-load state tracks original coordinates as map keys move. Paths are resolved before normalization loses their source coordinates. Inherited values retain their contributing origins; CLI path assignments use invocation origin. See [document paths](../../internal/core/config/document_paths.go) and [pipeline document normalization](../../internal/core/config/pipeline_document.go). ConfigKit owns parsing, imports, overlays, inheritance, typed composition, and provenance. The application supplies meaning through supported rules. It does not implement another inheritance resolver or translate retired inputs. [The public reference](../config.md#imports-and-sibling-inheritance) owns exact presence/null/list rules and processing order. `Config.Validate` checks application-only state and pipeline structure without requiring registered modules. Catalog-dependent compatibility belongs to resolution. Configuration does not parse a source transcript, materialize references, construct modules, or allocate run storage. ## Production Source Assembly `nativeLoaders.application` selects the main source and uses `configkit.LoadLayered` with the application definition, native underlays, selected overlay, and explicit overrides. Underlays come from bundled provider resources, ordinary embedded application content, and main-relative operator companions. Native source/filesystem contexts survive the load. The embedded assets package supplies content, not registration behavior. The operator companion uses a native main-relative context; it follows the selected main rather than rediscovering the working directory. Strict peers, optional absence, imports/destinations, and whole-record resource replacement remain native composition. Source grammar and precedence belong in [Configuration](../config.md#configuration-discovery-and-precedence). Core `Load`/`LoadSource` entry points support selected sources and the same definition/conversion for direct consumers and tests. They do not replace the production composition root's underlay assembly. Do not accidentally introduce a second production load by combining those paths. ## Result Lifetime And Runtime Conversion `LoadedConfig.Result()` exposes the original typed result for intentional native handoff. `FromResult` derives pipeline runtime settings without loading sources or serializing settings again. `RuntimeConfig` returns a detached copy; the native PromptKit configuration stays with its owning result/engine rather than being copied into a private runtime wrapper. `MainSourcePath` reads the retained non-imported main-file evidence. It does not repeat discovery or assume the first acquired file is the main. Within one invocation, `nativeLoaders` retains results by complete `ckconfig.Selection`, including overlay and override presence/values. Captured override containers are copied. A repeated identical selection returns the same result; distinct diff sides remain distinct selections. The engine is constructed lazily once for its retained result. This is invocation state, not a process-wide persistent loader cache. `NewFromConfig` consumes the completed result, preserving native contexts and inspection evidence without rerunning callbacks or adding underlays. Runtime-only HTTP/client settings and test provider options stay at engine construction. [PromptKit's application-owned-load contract][handoff] owns the library API. ## Effective Resolution And Preflight `Config.Resolve` clones configuration, resolves an empty programmatic cache-root selection, validates structure, and passes selected pipeline/lanes, profile/cache overrides, and exact reference changes to `pipeline.ResolvePipeline`. The framework resolves module/default/validator/type/reference compatibility and concrete producer controls before execution. Input slices/maps and the original configuration do not become mutable aliases of the effective result. Presence-aware selections preserve explicit invocation profile clearing, cache overrides, and zero semantic-turn controls rather than collapsing into omission. Deterministic bindings remain separate from LLM roles. A resolved-composition digest is not an accepted-artifact cache key; [state ownership](state.md) is a different boundary. Preflight consumes resolved data, the catalog, and the captured engine when model roles are selected. It checks static initial/correction/validator dependencies and applicable explicit/default profiles. It does not load configuration, construct modules, read reference/input bytes, or manufacture a request to prove readiness. Partial profiles remain valid; dynamic request selections are runtime checks. ## Inspection And Sensitive Values Native whole-app and focused views use retained ConfigKit evidence. Existing effective/explanation writers delegate to that result rather than walking YAML. Application sensitivity rules and native resource sensitivity participate in the same definition. Source/runtime option containers must not be independently reserialized as an alternative secret-handling mechanism. Do not infer that arbitrary source, prompt, provider, or module-option strings are safe to disclose. Capture uses native inspection and exact marked-secret paths, not heuristic application-text rewriting. See [CLI composition](cli.md) and [LLM integration](llm.md) for those consumers. ## Focused Verification - [Document/native settings tests](../../internal/core/config/native_settings_test.go) prove typed handoff, native rules, source-relative messages, and secret-aware views. - [Path tests](../../internal/core/config/document_paths_test.go) and [inheritance tests](../../internal/core/config/inheritance_test.go) cover origins, explicit presence, overlays, and source/runtime ownership. - [Control tests](../../internal/core/config/validation_policy_contract_test.go) cover loaded omission/zero and resolved controls. - [Effective resolution tests](../../internal/core/config/effective_config_contract_test.go) cover catalog checks, selection, and detached results. - [CLI loader tests](../../internal/cli/native_load_test.go) cover actual production underlays, strict companions, imports, frozen messages, and distinct selections. [Schema-load tests](../../internal/cli/native_schema_load_test.go) exercise native operator schema preparation/execution. Use focused configuration and CLI tests when changing this handoff. The [development guide](../development.md#validation) owns repository-wide checks. [handoff]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#reuse-an-application-owned-load