diff --git a/docs/roadmap/discovery.md b/docs/roadmap/discovery.md index cf49eef..f4033ef 100644 --- a/docs/roadmap/discovery.md +++ b/docs/roadmap/discovery.md @@ -260,6 +260,26 @@ on overlays with explicit context. Both ways of obtaining an absent main input have the same behavior. Implementation must cover this lifecycle change as well as candidate selection. +### Empty Composition And Implicit Preset Selection (OD-4 — Settled) + +Require explicit preset or search selection to activate a convention. Supplying +no presets or custom searches produces no candidates and activates no implicit +fallback. Empty custom path lists and explicitly empty filename-group selections +also contribute no candidates. An empty component does not prevent later +components from contributing candidates. + +If the complete search is empty, an optional search follows the absent-main +lifecycle settled under OD-3; a required search fails as exhausted. Empty lists +are valid, supporting consumers that construct their searches programmatically. + +Distinguish omission from an explicitly empty filename selection for a directory +search. Omitting the selection uses the agreed `[Named, Generic]` default; +explicitly selecting an empty list means no filenames. The eventual API must +represent both intentions clearly. Presets retain their specified filename groups. + +Selecting a single preset keeps the simple case concise. Search-wide requiredness +provides the check for consumers that must find a configuration file. + ### Placement, Provenance, And Existing Features The selected file participates as the actual file source. Preserve its physical @@ -285,7 +305,8 @@ The subsequent implementation plan should cover: - Define filename-group, directory-search, preset, and search-source representations, slug validation, and a search-wide requiredness option. Keep construction - separate from acquisition and the simple preset selection concise. + separate from acquisition and the simple preset selection concise. Distinguish + omitted and explicitly empty directory-search filename selections. - Implement ordered expansion and concatenation for presets, filename groups, custom searches, and explicit file candidates, followed by first-match selection through existing file access. Resolve each source once per consumption before @@ -298,6 +319,7 @@ The subsequent implementation plan should cover: - Exercise preset, directory, filename-group, and filename ordering, reversed group precedence, the Unix system preset's 14 candidates and named-only `/etc` search, custom-list composition, both filename extensions, no-match behavior, + empty components and searches, omitted versus empty filename selections, required searches, unavailable preset bases, errors that must stop fallback, repeated loads, and untouched explicit `File` behavior. Cover imports, overlays, underlays, defaults, CLI, source versions, @@ -315,23 +337,6 @@ its in-progress changes are part of a fixed implementation baseline. ## Open Decisions -### OD-4 — Empty Composition And Implicit Preset Selection - -**Recommendation:** require explicit preset or search selection to activate a -convention. An empty search composition has no candidates: optional search contributes no -source, and required search fails as exhausted. Empty custom lists, including -empty filename-group selections, follow the same rule. This supports programmatic -list construction and introduces no hidden -system, user, or working-directory fallback. One explicitly selected preset -still gives the simple application a short call. - -**Alternative:** let omission of searches select a documented default preset. -This shortens the simplest call, but omission and an intentionally empty computed -list would need distinguishable representations. It also requires choosing a -default convention across platforms and application styles. Another alternative -is to reject an empty composition as invalid; that catches accidental empty lists -but adds a special case beyond the search-wide requiredness rule. - ### OD-5 — Slugs And Custom Path Interpretation **Recommendation:** require a nonempty single-component slug when a selected