62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# 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](../config.md) owns implemented behavior.
|