From 66fa5585c1190581e96ec42102ce745c3869ba6d Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 4 Oct 2026 18:58:10 +0000 Subject: [PATCH] Clarify ConfigKit configuration ownership --- ...te-configuration-mechanics-to-configkit.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/adr/0020-delegate-configuration-mechanics-to-configkit.md diff --git a/docs/adr/0020-delegate-configuration-mechanics-to-configkit.md b/docs/adr/0020-delegate-configuration-mechanics-to-configkit.md new file mode 100644 index 00000000..3e2ae6a9 --- /dev/null +++ b/docs/adr/0020-delegate-configuration-mechanics-to-configkit.md @@ -0,0 +1,49 @@ +# ADR-0020: Delegate configuration mechanics to ConfigKit + +**Status:** Accepted +**Date:** 2026-10-04 + +## Context + +[ADR-0018](0018-adopt-configkit.md) 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.