Files
notarius/docs/internal/configuration.md

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

Use focused configuration and CLI tests when changing this handoff. The development guide owns repository-wide checks.