8.6 KiB
Configuration Internals
This guide explains the maintained configuration boundary and its composition-root handoff. Configuration owns source selection, syntax, fields, defaults, and selectable modules; CLI Reference owns invocation. Architecture defines ownership. Do not infer operator contracts from private helper choices here.
Owners And Handoffs
| Owner | Responsibility |
|---|---|
| core/config definition | Typed application document, native PromptKit configuration rules, application resolution/validation. |
| CLI loaders | Main-source selection, native underlays, invocation-local result/engine reuse. |
| LoadedConfig | Retain the original result and derive independently owned runtime pipeline configuration. |
| Config.Resolve | Resolve a selected pipeline against the supplied catalog. |
| preflight | Check known native resources from resolved composition and supplied engine. |
| Pipeline preparation | Construct typed execution collaborators from resolved, materialized inputs; see Pipeline Internals. |
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 and pipeline document normalization.
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 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.
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 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 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 and LLM integration for those consumers.
Focused Verification
- Document/native settings tests prove typed handoff, native rules, source-relative messages, and secret-aware views.
- Path tests and inheritance tests cover origins, explicit presence, overlays, and source/runtime ownership.
- Control tests cover loaded omission/zero and resolved controls.
- Effective resolution tests cover catalog checks, selection, and detached results.
- CLI loader tests cover actual production underlays, strict companions, imports, frozen messages, and distinct selections. Schema-load tests exercise native operator schema preparation/execution.
Use focused configuration and CLI tests when changing this handoff. The development guide owns repository-wide checks.