Files
notarius/docs/adr/0020-delegate-configuration-mechanics-to-configkit.md

2.3 KiB

ADR-0020: Delegate configuration mechanics to ConfigKit

Status: Accepted Date: 2026-10-04

Context

ADR-0018 establishes ConfigKit as Notarius's configuration loader. This decision clarifies the continuing ownership boundary as ConfigKit's capabilities evolve.

Decision

ConfigKit owns configuration mechanics: source loading, parsing, imports, composition, overlays, inheritance, presence tracking, provenance, and inspection. Notarius adopts those semantics through ConfigKit's public APIs.

Notarius owns application meaning: its configuration schema, version, defaults, field normalization, validity checks, and pipeline/module compatibility. It supplies application-specific defaults, normalization, and validation through ConfigKit's supported extension points. Source-origin metadata supports application rules such as declaration-relative filesystem paths.

Notarius selects configuration inputs and options through the public API. ConfigKit resolves those inputs and delivers the final application document with source composition and application-field normalization complete. Notarius converts that document into its runtime configuration and performs catalog-dependent pipeline resolution and runtime preparation afterward.

Operator-requested effective configuration and setting explanations use ConfigKit's inspection APIs. Application validation evaluates the resolved configuration. Changes to general configuration mechanics are pursued upstream in ConfigKit and adopted through its supported API.

Alternatives considered

  • Application-owned configuration loading provides direct control over source semantics and assigns parsing, composition, and provenance maintenance to Notarius.
  • Shared ownership of configuration mechanics allows local adaptations and requires maintaining coordinated semantics across ConfigKit and Notarius.

Consequences

ConfigKit provides a coherent configuration-resolution and inspection contract. Notarius's configuration work concentrates on application semantics and operator integration. Upstream upgrades are evaluated against this ownership boundary and the application's deliberately selected requirements. This decision clarifies ADR-0018 while retaining its adoption and application-format decisions.