2.8 KiB
ADR 0020: Scope Configuration Controls to Document Roots
Status
Accepted.
Date
2026-11-01
Context
ConfigKit interprets configuration controls during source acquisition, before placing and composing source payloads. Reserving the control name throughout application data restricts paths unrelated to source-document controls. The source-local position of a control and the effective application path of a value are different coordinates, even when their path text is identical.
Decision
Use config as the single control mapping name at the root of each acquired
source document. Interpret each source's controls before placing its payload,
using the existing context-specific grammar and import opt-in. A source retains
its own document root regardless of its eventual destination, including when
mounted below another value or as a sequence record.
Below a source root, config is ordinary application data, including in
sequence records and selected overlays. Control-looking children in such data
do not activate controls. Application-root config data produced by placement,
defaults, CLI assignment, or resolution is also ordinary data. Placement and
later lifecycle operations do not create another source-document parsing pass.
The former spellings configkit and _configkit are ordinary application keys
at any depth, subject to normal schema and structural rules; they are not
control aliases. Source-version checks protect actual source-local controls,
not an application path merely because its spelling matches. Existing extends
inheritance semantics and restrictions remain in force.
Alternatives Considered
- Reserve the control name throughout application data. This conflates source-document syntax with application paths and prevents ordinary fields unrelated to control interpretation.
- Recognize controls again after placement or later operations. This makes application data acquire control semantics according to its destination and introduces a second interpretation pass.
- Support multiple or configurable control spellings. This makes control interpretation ambiguous and expands the configuration contract.
Consequences
Control evidence uses source-local coordinates while assembled values use
application coordinates. Existing source identities and contexts distinguish
these uses without a new inspection-record format. Consumers must migrate
genuine old control blocks and account for source-root application fields
named config; ordinary nested and assembled root fields remain available.
The completed feature roadmap and implementation plan are preserved in Git
history at c63f4ff under docs/roadmap/, for example
git show c63f4ff:docs/roadmap/implementation.md.
The configuration contract owns implemented behavior.