Record relative import destination decision and baseline

This commit is contained in:
2026-10-14 17:17:50 +00:00
parent 934c1022e0
commit a8beb3e620
3 changed files with 99 additions and 5 deletions

View File

@@ -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

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

View File

@@ -1,7 +1,7 @@
# Implement relative import destinations
Status: planned. Execute Stage 1 through Stage 9 in order, one focused stage per
Luna implementation prompt. The
Status: in progress. Execute Stage 1 through Stage 9 in order, one focused stage
per Luna implementation prompt. The
[feature roadmap](relative-import-destinations.md) owns the approved target and
syntax; this document owns implementation decisions, sequencing, and evidence.
@@ -130,7 +130,7 @@ also proposes independent specification headers, which are outside this plan.
## Stage 1 — Capture the baseline and record the extension
Status: planned. Scope: baseline evidence and one ADR; no production code.
Status: complete. Scope: baseline evidence and one ADR; no production code.
1. Read the feature roadmap, relative-import request/acceptance rows, applicable
policies, ADR 0011, and the owner map below. Confirm the worktree and baseline.
@@ -152,6 +152,21 @@ Status: planned. Scope: baseline evidence and one ADR; no production code.
Validate: whitespace and local-documentation-link checks. Done: baseline and
decision are recorded; implemented behavior is unchanged.
Baseline evidence (2026-10-14): revision `934c1022e038115475c1d33dd85216855b8be522`
on `main`; the worktree was clean and four commits ahead of `origin/main`.
Local toolchain: `go1.26.8 linux/amd64`. `./scripts/check.sh` passed, including
format/whitespace checks, all Go tests, vet, build, examples, local links, and
package-boundary checks. No environmental limitations. Existing coverage is
centered in `internal/engine/parse_test.go`, `imports_test.go`, `glob_test.go`,
`native_filesystem_test.go`, `version_path_test.go`, and the `destination_*_test.go`
files; public/lifecycle coverage includes `facade_destination_test.go`,
`facade_layered_test.go`, `facade_version_test.go`,
`facade_resource_context_test.go`, `facade_inheritance_test.go`, and
`facade_diff_test.go`, with engine resource and history coverage in
`resource_context_test.go` and `inheritance_history_test.go`.
Done: baseline and decision are recorded; implemented behavior is unchanged.
## Stage 2 — Refactor traversal to explicit per-document placement
Status: planned. Scope: private context plumbing; old syntax remains unchanged.