149 lines
8.6 KiB
Markdown
149 lines
8.6 KiB
Markdown
# 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
|