1.4 KiB
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 owns the governing boundary; the target design 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.