Files
notarius/docs/internal/configuration.md

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