2.5 KiB
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.