diff --git a/docs/roadmap/overlays.md b/docs/roadmap/overlays.md index 13ba0c0..28cb1dc 100644 --- a/docs/roadmap/overlays.md +++ b/docs/roadmap/overlays.md @@ -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