38 lines
1.5 KiB
Markdown
38 lines
1.5 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 [current configuration contract](../config.md#strict-document-composition) owns
|
|
the operation table and selected-profile overlay behavior.
|
|
|
|
## 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.
|