38 lines
1.4 KiB
Markdown
38 lines
1.4 KiB
Markdown
# ADR 0001: Separate Composition and Overlay
|
|
|
|
## Status
|
|
|
|
Accepted. This records a design decision, not implementation completion.
|
|
|
|
## Date
|
|
|
|
2026-09-06
|
|
|
|
## Context
|
|
|
|
Configuration fragments allow independent parts of an application to contribute
|
|
settings. Treating every file as a precedence layer makes accidental duplicates
|
|
silently depend on file order. Profiles, however, need intentional replacement.
|
|
|
|
## Decision
|
|
|
|
Use distinct strict-composition and intentional-overlay operations. Composition
|
|
rejects conflicting definitions; overlay provides explicit precedence. Keep the
|
|
operations opinionated rather than adding arbitrary per-field merge strategies.
|
|
The [architecture policy](../policy/architecture.md) owns the governing boundary;
|
|
the [target design](../roadmap/initial.md#composition-and-overlay) owns the planned
|
|
operation table until its current contract lands.
|
|
|
|
## Alternatives considered
|
|
|
|
- Last-wins loading for all files: convenient but conceals accidental conflicts.
|
|
- Strict loading for every layer: catches conflicts but cannot express profiles.
|
|
- User-defined merge policies: flexible but weakens consistency and expands the API.
|
|
|
|
## Consequences
|
|
|
|
Consumers must distinguish modular contributions from intentional overrides.
|
|
Diagnostics need both conflicting sources. File order remains useful for stable
|
|
traversal and reporting but cannot silently authorize replacement. Named mappings
|
|
are the natural representation for independently contributed entries.
|