54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# ADR-0018: Adopt ConfigKit for configuration loading
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-09-13
|
|
|
|
## Context
|
|
|
|
Notarius's former configuration boundary owned strict YAML parsing, input
|
|
presence bookkeeping, defaults, normalization, environment overlays, and
|
|
configuration inspection. Those general-purpose responsibilities had grown
|
|
alongside application-specific pipeline and module semantics.
|
|
|
|
ConfigKit v0.3.0 provides strict typed YAML loading, imports, configuration
|
|
profiles, explicit CLI overrides, recorded defaults and normalization, safe
|
|
inspection rendering, and released source-origin APIs. The application needs
|
|
those source records to resolve filesystem paths according to the file that
|
|
supplied a surviving declaration.
|
|
|
|
## Decision
|
|
|
|
Notarius will adopt the root public `gitea.maximumdirect.net/eric/ConfigKit`
|
|
package at v0.3.0 for its version 5 configuration contract. ConfigKit owns
|
|
source composition, strict decoding, input presence, metadata, and safe
|
|
effective/explanation rendering. Notarius retains its typed document schema,
|
|
field semantics, runtime conversion, catalog-dependent pipeline resolution,
|
|
PromptKit profile handling, and physical run preparation.
|
|
|
|
Version 5 is a deliberate breaking file-contract change. It uses canonical
|
|
object module bindings and reference sources, and enables ConfigKit imports
|
|
and configuration profiles. The selected configuration file's canonical
|
|
directory is the base for its declared application paths; ConfigKit's released
|
|
`Resolution.InputInfo` and `Resolution.Source` APIs provide their origins.
|
|
|
|
`NOTARIUS_CONFIG` remains file discovery, while field-level operational
|
|
environment overlays are retired. Explicit configuration-valued CLI flags are
|
|
represented as ConfigKit overrides; invocation actions remain outside that
|
|
boundary.
|
|
|
|
## Alternatives considered
|
|
|
|
- Continue extending the custom YAML loader. This preserves duplicated
|
|
general-purpose parsing, presence, composition, and inspection machinery.
|
|
- Retain version 4 alongside version 5. This would leave a supported dual
|
|
configuration boundary and delay removal of the machinery being replaced.
|
|
- Wrap ConfigKit in a compatibility pre-parser. This weakens ConfigKit's
|
|
strict contract and recreates the application-owned parser complexity.
|
|
|
|
## Consequences
|
|
|
|
The released application has one ConfigKit-backed loader and one version 5
|
|
contract. Operator documentation and maintained examples move with the cutover.
|
|
ConfigKit metadata is retained only at the configuration publication boundary;
|
|
its types do not become module or runtime pipeline interfaces.
|