diff --git a/docs/roadmap/discovery.md b/docs/roadmap/discovery.md index 713cd85..b773500 100644 --- a/docs/roadmap/discovery.md +++ b/docs/roadmap/discovery.md @@ -1,6 +1,7 @@ # Composable Configuration Discovery Roadmap -Status: proposal with OD-1 through OD-5 settled and integrated below. +Status: proposal with OD-1 through OD-5 and the final review clarifications +settled and integrated below. This document describes future work, not an implemented contract. A staged implementation plan will follow review of the complete roadmap. @@ -61,7 +62,8 @@ groups are: The default selection is `[Named, Generic]`, producing the six filenames above in that order. A directory search may select different groups or reverse their precedence, such as `[Generic, Named]`, while retaining each group's internal -order. Consumers can also supply custom filenames. +order. Consumers can also supply custom filenames, subject to the literal +single-component rules under OD-5 below. **Search presets** bundle ordered directory searches. Consumers can select a complete preset for the simple case or compose presets, custom directory searches, @@ -216,6 +218,8 @@ the single-preset case concise. Resolve directory bases only as the ordered search reaches them. Once an earlier candidate is selected, later searches do not resolve their bases. Static invalid search arguments still fail ordinary option validation before source acquisition. +An explicitly empty filename selection skips directory resolution as specified +under OD-4; it has no candidates to locate. If a selected directory's base cannot be resolved, stop and report the error. A missing directory or candidate file beneath a resolved base allows the search @@ -248,6 +252,15 @@ filesystem context to locate the overlay. Do not infer an overlay root from the first or last searched directory. A missing selected overlay remains an error; absence of a main file does not silently disable a requested overlay. +For an absent main input, a host filesystem context specifying only `Root` is +sufficient to locate the overlay; no main-file `BaseDir` is needed. If discovery +selects a host file, retain the normal file-context rules: the selected file +determines its base directory, an explicit `BaseDir` is rejected, and the file +must be contained within any supplied root. This allows one root-only context +to work with both selected and absent main inputs, subject to those existing +root and containment checks. An invalid context is an error, not a reason to +resume discovery. + Defaults, CLI overrides, application resolution, and validation continue through the normal lifecycle. Main-version checking receives an absent main input and may reject it under the application's existing policy. Create no synthetic empty @@ -266,6 +279,11 @@ 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. +A directory search with an explicitly empty filename selection does not resolve +its directory base. Static argument validation still applies. This gives empty +selections their no-candidate meaning without introducing directory-resolution +errors for a search that cannot select a file. + 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. @@ -296,6 +314,13 @@ syntax. Consumers can construct expanded paths themselves; User and Home presets provide the common directory-resolution conveniences. These rules keep custom paths consistent with explicit file loading. +Custom filenames within directory searches are literal single filename +components. They cannot be absolute paths or contain subdirectory components; +use custom directory searches or explicit file candidates for those layouts. +They receive no application-name placeholder expansion. The Named group supplies +application-name expansion, while consumers may construct custom filenames +themselves before supplying them. + ### Placement, Provenance, And Existing Features The selected file participates as the actual file source. Preserve its physical @@ -329,14 +354,17 @@ The subsequent implementation plan should cover: entering its parse and composition lifecycle. - Integrate selected and absent outcomes with ordinary and layered main inputs, placement, imports, application version checking, and overlay contexts according - to OD-3. Preserve ownership and close acquired handles on success and failure. + to OD-3, including root-only host contexts for absent main inputs and normal + file-context checks when a file is selected. Preserve ownership and close + acquired handles on success and failure. - Preserve real selected-source metadata and safe diagnostics without treating absent candidates as configuration contributions. - 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, - slug-dependent and slug-independent searches, literal custom paths, + skipped directory resolution for empty filename selections, slug-dependent and + slug-independent searches, literal custom paths and filename components, 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,