Record relative import destination decision and baseline
This commit is contained in:
@@ -3,8 +3,11 @@
|
||||
## Status
|
||||
|
||||
Accepted. The [input-destinations roadmap](../roadmap/input-destinations.md)
|
||||
owns implementation status. The completed implementation plan and evidence are
|
||||
preserved at `315f464:docs/roadmap/implementation.md` in Git history.
|
||||
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
|
||||
|
||||
|
||||
76
docs/adr/0012-relative-import-destinations.md
Normal file
76
docs/adr/0012-relative-import-destinations.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# ADR 0012: Place Imported Configuration at Relative Destinations
|
||||
|
||||
## Status
|
||||
|
||||
Accepted. The [relative-import destinations roadmap](../roadmap/relative-import-destinations.md)
|
||||
owns the approved public behavior; the implementation plan records delivery
|
||||
status and evidence.
|
||||
|
||||
## Date
|
||||
|
||||
2026-10-14
|
||||
|
||||
## Context
|
||||
|
||||
ConfigKit can place an input document at a literal mapping path while retaining
|
||||
source identity, composition, and inspection in its normal loading lifecycle.
|
||||
An importing document can currently bring in other documents, but those
|
||||
contributions inherit only the importing input's destination. Consumers that
|
||||
assemble a collection therefore cannot declare the layout of imported
|
||||
fragments alongside the import itself without rewriting source documents or
|
||||
performing another merge outside ConfigKit.
|
||||
|
||||
The extension should reuse input placement and the existing import lifecycle.
|
||||
Logical application placement must remain independent from physical path
|
||||
resolution, source identity, precedence, and resource ownership.
|
||||
|
||||
## Decision
|
||||
|
||||
Add an optional `destination` field to each YAML import declaration. Its value
|
||||
is a sequence of strings representing literal mapping-key segments. Omission
|
||||
and an empty sequence add no segments. A non-empty destination appends to the
|
||||
effective destination of the immediately importing document; nested imports
|
||||
continue from the resulting child destination. Every match of one glob
|
||||
declaration receives the same computed destination.
|
||||
|
||||
Use the existing input-destination validation and reserved-key rules. Do not
|
||||
interpret destination segments as filesystem paths, separators, sequence
|
||||
indices, or root-reset instructions. Physical import paths continue to resolve
|
||||
from their declaring source under existing containment rules.
|
||||
|
||||
Imports remain in their existing strict-composition group. A destination does
|
||||
not grant precedence, bypass cycle or repeated-source rules, or change source
|
||||
identity. Existing placement, version ownership, source records, diagnostics,
|
||||
resource contexts, inheritance, history, and inspection mechanisms continue to
|
||||
govern the placed contributions. No public Go entry point or independent
|
||||
specification-header behavior is introduced.
|
||||
|
||||
This is additive YAML functionality and is minor-release work. Version
|
||||
selection, release notes, roadmap retirement, and publication remain separate
|
||||
release-preparation work.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- **Require complete application-root destinations on every import.** This
|
||||
avoids inherited context but repeats collection prefixes in nested source
|
||||
declarations and does not express placement relative to the importing
|
||||
document.
|
||||
- **Encode destinations as dotted or slash-delimited strings.** This introduces
|
||||
separator and escaping rules even though existing paths already represent
|
||||
literal mapping keys as segments.
|
||||
- **Rewrite or merge imported documents in consumers.** This duplicates source
|
||||
placement, strict composition, attribution, and inspection behavior outside
|
||||
ConfigKit's loading lifecycle.
|
||||
- **Add independent specification headers or collection-specific validation.**
|
||||
These are separate design questions and are not required to declare relative
|
||||
placement.
|
||||
|
||||
## Consequences
|
||||
|
||||
Import declarations can describe the logical placement of their contributions
|
||||
while preserving the physical source and existing composition lifecycle.
|
||||
Placement is immediate-parent-relative, so nested imports accumulate their
|
||||
declared segments and sibling declarations remain independent. The feature is
|
||||
implemented behind the existing public loading surface; detailed validation,
|
||||
diagnostic, accounting, and inspection requirements are tracked by the
|
||||
implementation roadmap.
|
||||
Reference in New Issue
Block a user