3.7 KiB
ADR 0011: Place Configuration Inputs at Mapping Destinations
Status
Accepted. The input-destinations roadmap
owns implementation status for input placement. The accepted relative-import
extension is recorded in ADR 0012, 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 by default; ADR 0012 extends this with an optional immediate-parent-relative YAML 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.