74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# ADR 0011: Place Configuration Inputs at Mapping Destinations
|
|
|
|
## Status
|
|
|
|
Accepted. The [input-destinations roadmap](../roadmap/input-destinations.md)
|
|
owns implementation status for input placement. The accepted relative-import
|
|
extension is recorded in [ADR 0012](0012-relative-import-destinations.md), with
|
|
delivery status in its implementation plan. The completed implementation plan
|
|
and evidence are preserved at `315f464:docs/roadmap/implementation.md` in Git
|
|
history.
|
|
|
|
## Date
|
|
|
|
2026-10-14
|
|
|
|
## Context
|
|
|
|
Consumers assembling collections of independently authored configuration
|
|
fragments need each source to contribute beneath a selected application path.
|
|
Requiring consumers to rewrite source documents or merge completed values would
|
|
separate placement from ConfigKit's existing composition, precedence, source
|
|
identity, and inspection behavior. Placement should remain part of the ordinary
|
|
loading lifecycle and preserve the root-owned public facade.
|
|
|
|
## Decision
|
|
|
|
Add an optional `Destination Path` to root-owned `Input` and expose the effective
|
|
destination on existing `SourceInfo` records. The empty path means the existing
|
|
application root. A non-empty destination is a sequence of literal mapping keys;
|
|
explicit sequence-index segments are invalid. Existing reserved structural keys
|
|
remain reserved, while keys that merely contain their spelling remain ordinary
|
|
keys.
|
|
|
|
Acquire and interpret each source using its original physical identity and
|
|
source-local directives, then place its application body before strict
|
|
composition and the existing final lifecycle. Imported application bodies
|
|
inherit the input destination. Placement applies to main and underlay inputs;
|
|
ordinary root loading, selected overlays, and CLI inputs retain root placement.
|
|
The main-owned version rule continues to check its effective application path
|
|
at its existing lifecycle point.
|
|
|
|
Placement preserves authored node locations and source identity. Introduced
|
|
mapping structure belongs to the contributing source and uses that document's
|
|
root location as its source-coordinate fallback. A present empty mapping
|
|
materializes its destination; an absent `NoSource` contributes nothing. The
|
|
result continues through the existing strict composition, overlay, inheritance,
|
|
typed loading, diagnostics, provenance, history, sensitivity, and resource
|
|
context mechanisms.
|
|
|
|
The added exported fields preserve keyed and zero-value struct use. Callers
|
|
using unkeyed composite literals for `Input` or `SourceInfo` must migrate to
|
|
keyed literals. Treat this feature as minor-release work; select the version and
|
|
document the compatibility impact during separately authorized release
|
|
preparation, consistent with the release policy.
|
|
|
|
## Alternatives considered
|
|
|
|
- **Rewrite or merge sources in consumers.** This makes each consumer reproduce
|
|
placement, strict composition, source attribution, and inspection semantics.
|
|
- **Add a separate loading entry point or public wrapper type.** This creates a
|
|
parallel API for a behavior that belongs to existing per-input loading.
|
|
- **Load each fragment as a complete application before placement.** This runs
|
|
defaults, decoding, resolution, and validation on incomplete fragments rather
|
|
than once on the assembled application.
|
|
|
|
## Consequences
|
|
|
|
Consumers can assemble contributions at effective mapping paths in one ordinary
|
|
layered load and inspect each source's placement through existing source
|
|
records. Paths, conflicts, and later application operations use the placed
|
|
structure while source coordinates and relative-resource contexts continue to
|
|
identify their original sources. Public field additions require release-note
|
|
guidance for callers using unkeyed literals.
|