diff --git a/docs/adr/0005-configkit-boundary.md b/docs/adr/0005-configkit-boundary.md new file mode 100644 index 0000000..22b34bc --- /dev/null +++ b/docs/adr/0005-configkit-boundary.md @@ -0,0 +1,71 @@ +# ADR 0005: Adopt ConfigKit's Configuration Boundary + +## Status + +Accepted. + +## Date + +2026-10-04. + +## Context + +Scriptorium uses ConfigKit to resolve application configuration. Adopting its +standard semantics across the application suite gives operators a consistent +configuration model and keeps configuration processing under a single owner. + +The application supplies its schema and domain rules through ConfigKit's public +definition API. ConfigKit returns the resolved configuration and inspection +information for use by Scriptorium. + +## Decision + +ConfigKit owns configuration loading and resolution semantics, including +decoding, imports, composition, precedence, overlays, inheritance, and +inspection. Scriptorium adopts those semantics through ConfigKit's supported +public APIs. + +Scriptorium owns its application schema, defaults, value normalization, and +domain validation. It supplies these rules through ConfigKit's definition +callbacks so they participate in the library's resolution and validation flow. +Scriptorium consumes the final, fully resolved configuration returned by that +flow. + +Scriptorium also owns application-facing choices: default discovery locations, +source and option selection, and the mapping of CLI inputs to ConfigKit options +and overrides. ConfigKit determines how the selected inputs are processed. + +Scriptorium may expose ConfigKit's inspection APIs through operator interfaces +when demand warrants them. ConfigKit owns the underlying inspection semantics; +Scriptorium owns their application-facing presentation. + +Resolution establishes configuration values. Runtime credentials, artifacts, +and downstream resources retain their respective preparation and execution +lifecycle. Promptkit owns its framework schema and domain rules when using +ConfigKit, consistent with [ADR 0004](0004-definition-boundary.md). + +## Alternatives Considered + +### Application-Owned Configuration Processing + +Scriptorium could implement loading and composition locally. This offers +application-specific flexibility, but duplicates ConfigKit's responsibilities +and creates recurring maintenance and semantic drift across applications. + +### ConfigKit-Owned Application Choices + +Scriptorium could delegate discovery conventions and domain defaults to the +library. This reduces local decisions, but places application-specific behavior +in a shared configuration mechanism. The selected boundary keeps those choices +with the application while using the library's processing semantics. + +## Consequences + +Configuration changes follow the ownership boundary: processing capabilities +belong in ConfigKit, and application rules use its supported extension points. +ConfigKit upgrades are evaluated for their effects on Scriptorium's selected +inputs, domain callbacks, and operator interfaces. + +The [architecture policy](../policy/architecture.md) owns current architectural +constraints, and the [configuration contract](../config.md) owns observable +application behavior. This ADR records the rationale for the ownership boundary.