base-layer/configkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Settle the direct overlay catalog format

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-10 02:56:28 +00:00
parent 5f001cf597
commit 22603f0e5b
1 changed files with 32 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/roadmap/overlays.md
View File

@@ -1,7 +1,8 @@
# Single-file named overlays
Status: proposal; strict composition between the two forms is accepted. Remaining
decisions are listed below. Not implemented. Implementation baseline: `ce6005c`.
Status: strict composition between the two forms and direct catalog structure
are settled. Remaining decisions are listed below. Not implemented.
Implementation baseline: `ce6005c`.
## Purpose
@@ -15,6 +16,12 @@ contributions, strictly composes them, and applies the resulting overlay once.
This follows [ADR 0001](../adr/0001-separate-composition-and-overlay.md): peer
composition and intentional precedence remain separate operations.
This roadmap extends file-based selected overlays. The selected contributions
compose as peers at the overlay stage; overlay definitions do not acquire
underlay or main-input precedence tiers. A configuration-wide catalog populated
through inline `config.overlays`, ordinary imports, or application underlays is
outside this feature's scope. No new application or source-control key is reserved.
## Current baseline
The [selected-overlay contract](../config.md#selected-overlays) currently loads
@@ -40,10 +47,11 @@ cleanup already cover the individual-file form.
### File layout and selection
The proposed catalog is a mapping from overlay names directly to overlay bodies:
The catalog is a mapping from overlay names directly to overlay bodies, without
an enclosing `overlays` key:
```yaml
# overlays.yml — proposed format
# overlays.yml — planned format
production:
service:
workers: 8
@@ -73,8 +81,8 @@ service:
If the individual file instead also defines `service.workers: 12`, ordinary
strict-composition conflict rules apply. File order grants no precedence.
The other catalog entries do not contribute to the selected configuration.
The exact catalog structure and its validation boundary remain in OD-1 through
OD-3; this example illustrates the recommended structure.
OD-1 settles this catalog structure. Source-version/control scope and the
validation boundary remain in OD-2 and OD-3.
Use the same lookup directory for the catalog and the existing `overlays/`
directory. Preserve ordinary versus layered lookup semantics, explicit context
@@ -187,20 +195,22 @@ benchmark campaign or release gate is required. Completion means applications
can select one named overlay from either or both forms with the same composition,
precedence, and inspection model.
## Settled Decisions
### OD-1: Catalog structure — settled
Use the direct name-to-body mapping illustrated above, with no enclosing
`overlays` mapping. The filename identifies the document's role; each named body
remains recognizable as an individual overlay file's contents. The top-level
mapping is a selection container and is not passed to application decoding.
Overlay names retain existing spelling and selection rules, including empty
selection and exact lowercase `default` meaning no overlay.
This settles the storage structure within the narrower file-based feature.
Source-version declarations and document controls remain subject to OD-2.
## Open Decisions
### OD-1: Catalog structure
**Recommendation:** use the direct name-to-body mapping illustrated above.
It adds only one enclosing mapping and keeps each body recognizable as an
ordinary overlay. The catalog wrapper is a selection container, not an application
document; overlay names retain existing spelling and selection rules. The special
`default` selection continues to mean no overlay.
**Alternative:** wrap entries under an `overlays` key, leaving space for catalog
metadata. This gives file-level headers an explicit home, but adds boilerplate
and another reserved structure before a need for catalog metadata is established.
### OD-2: Source-version declarations and document controls
**Recommendation:** treat each selected body as the overlay's logical document
@@ -218,9 +228,10 @@ physical document from the selected logical overlay in version processing and
inspection; it must not silently change source-version semantics for other inputs.
**Alternative:** declare the version and shared controls once at catalog level,
with entries inheriting them. This reduces repeated headers but needs the wrapper
from OD-1 or another metadata convention, plus rules for shared versus per-entry
controls. It also makes a standalone overlay body differ from its catalog form.
with entries inheriting them. This reduces repeated headers but needs a metadata
convention alongside the named entries, including rules for collisions with overlay
names and shared versus per-entry controls. It must respect OD-1's direct mapping
and also makes a standalone overlay body differ from its catalog form.
### OD-3: Validation of unselected bodies