# 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.