From b746dcc609408cc2a8e37caaee3d94dcff3520b8 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 24 Oct 2026 01:51:08 +0000 Subject: [PATCH] Settle discovery behavior when no main file is found --- docs/roadmap/discovery.md | 51 +++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 26 deletions(-) diff --git a/docs/roadmap/discovery.md b/docs/roadmap/discovery.md index 7b3d371..cf49eef 100644 --- a/docs/roadmap/discovery.md +++ b/docs/roadmap/discovery.md @@ -183,7 +183,7 @@ searches changes search priority. | A candidate file is selected | Stop searching and load that file. | | Candidate is inaccessible, unreadable, or not an accepted file type | Fail using normal source diagnostics. | | Selected file fails parsing, version checks, composition, decoding, or validation | Fail without trying another candidate. | -| Entire search has no match | Absence is permitted by default; continue through applicable defaults and normal validation. The interaction with other inputs is addressed under OD-3. | +| Entire search has no match | Absence is permitted by default; follow the shared absent-main lifecycle settled under OD-3 below. | | Entire search has no match and is required | Fail with a diagnostic explaining the unsuccessful search. | | Caller explicitly uses `File(path)` | Retain existing exclusive-file behavior, including errors for a missing file. | @@ -236,6 +236,30 @@ This keeps search priority predictable when directory resolution fails. Consumer select the presets appropriate to their application and environment; this proposal does not add an option to skip unavailable bases or unsupported presets. +### No Match, Imports, And Selected Overlays (OD-3 — Settled) + +Use a shared absent-main lifecycle for optional no-match and explicit `NoSource()`. +Allow imports to be enabled when the main file is absent: there are no main-file +import declarations to process, and enablement does not introduce automatic +directory scanning. Other actual sources retain their normal import behavior. +In layered loads, process underlays normally and retain the existing explicit +`OverlayFilesystem` requirement for an active overlay. + +For ordinary loads with an active overlay and no main file, require an explicit +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. + +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 +document or source record for the absent main file. + +This deliberately relaxes the current `NoSource()` restrictions on imports and +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. + ### Placement, Provenance, And Existing Features The selected file participates as the actual file source. Preserve its physical @@ -291,31 +315,6 @@ its in-progress changes are part of a fixed implementation baseline. ## Open Decisions -### OD-3 — No Match, Imports, And Selected Overlays - -**Recommendation:** use a shared absent-main lifecycle for optional no-match and -explicit `NoSource()`. Allow import enablement when the main file is absent; -there are no main-file declarations to traverse. Other actual sources retain -their normal import behavior. In layered loads, retain underlays and the existing -explicit overlay-filesystem requirement. - -For ordinary loads with an active overlay and no main file, require an explicit -filesystem context. Do not infer an overlay root from the first or last searched -directory. A missing selected overlay remains an error. Defaults, CLI overrides, -resolution, and validation continue normally, and main-version checking receives -absence rather than a fabricated document. - -This would deliberately relax the current `NoSource()` restrictions on imports -and on overlays with explicit context. It keeps one meaning for absent main input -and lets optional configuration remain optional without silently ignoring a -requested overlay. It requires lifecycle work beyond candidate selection. - -**Alternative:** map no-match to the current `NoSource()` contract and retain its -restrictions. This minimizes lifecycle changes, but an otherwise valid optional -search with imports enabled can fail solely because no file was found, and -ordinary overlay-only loading would remain unavailable. A special absent-search -case could avoid changing `NoSource()`, at the cost of two different absence rules. - ### OD-4 — Empty Composition And Implicit Preset Selection **Recommendation:** require explicit preset or search selection to activate a