diff --git a/docs/roadmap/main-relative-inputs.md b/docs/roadmap/main-relative-inputs.md index 8a4ff58..3a5eec9 100644 --- a/docs/roadmap/main-relative-inputs.md +++ b/docs/roadmap/main-relative-inputs.md @@ -94,10 +94,11 @@ outside this feature; it is not a second spelling for current overlay lookup. ### Companion underlays -The application declares an underlay `Input` containing native imports and -selects main-derived filesystem binding for that input. `Mapping` and `Bytes` -are first-class supported sources for this use. OD-1 settles the public API -structure below; no new operator-facing YAML syntax is needed. +The application declares a non-file underlay `Input` containing native imports +and selects main-derived filesystem binding for that input. `Mapping`, `Bytes`, +and `Reader` are supported sources for this use. OD-1 settles the public API +structure and receiving-input scope below; no new operator-facing YAML syntax +is needed. Once the main context is resolved, ConfigKit inherits its base, namespace, and containment root under OD-3 and OD-4. File mains supply their resolved directory; @@ -148,9 +149,11 @@ Optional discovery may find no main file while defaults and CLI settings still permit a successful application load. An explicit context on that absent main can still supply a usable base under OD-4. When no usable base is available, skip optional companion import expansion while retaining the declaring input's -ordinary payload and validation. Required imports still fail. Applications can -require a base or supply an explicit fallback context on each derived binding. -OD-2 records the settled precedence, skip scope, and fallback behavior. +ordinary payload and validation. Imports requiring targets or a nonempty selection +still fail; an empty `path: []` retains its existing no-op behavior even when +required. Applications can independently require a base or supply an explicit +fallback context on each derived binding. OD-2 records the settled precedence, +validation timing, skip scope, and fallback behavior. Do not infer a directory from unsuccessful candidates or silently use the working directory. An application may explicitly choose the working directory as its @@ -168,7 +171,8 @@ defaults, CLI, resolution, secret, and validation phases. No application context callback, second discovery API, or preliminary full load is required. Check static declarations during preflight where possible; defer checks requiring -the selected directory. Do not introduce a global ordering guarantee for unrelated +the selected directory. Resolve and check fallback filesystem locations only when +selected under OD-2. Do not introduce a global ordering guarantee for unrelated diagnostics or filesystem checks. Selected-file and companion acquisition errors remain terminal rather than restarting discovery. @@ -180,6 +184,13 @@ source identity, locations, precedence layer, underlay index, and passive resour context. Preserve namespace identity, repetition scope, shared budgets, detached inspection, and acquisition-handle cleanup. +Optional imports skipped because no base is available retain their declaring +source's normal evidence. Skipping does not manufacture acquired sources, +resource contexts, or evidence of completed filesystem searches. In particular, +do not add `EmptyImportSelections` records solely because expansion was skipped +for lack of a base. Preserve existing evidence for declarations that actually +complete; no new inspection API is needed for this feature. + Successful existing ordinary and explicitly configured layered loads should retain their behavior. Automatically deriving a layered overlay context intentionally relaxes the former missing-context error. Companion directory conventions are @@ -231,8 +242,10 @@ Validate behavior through the public loading boundary, including: - Native file mains, bytes/readers/mappings with explicit host or native contexts, and absent mains with explicit contexts. Cover absent host root-only contexts, missing and invalid contexts, and context reuse without enabling main imports. -- Mapping and bytes underlays containing optional named-file and recursive +- Mapping, bytes, and reader underlays containing optional named-file and recursive directory imports with `*.yml`/`*.yaml` filtering and mounted destinations. +- Receiving-input scope: active bindings on main inputs and file-backed underlays + fail with option errors; concrete context overrides retain their precedence. - File only, directory only, both, neither, empty directories, and invalid or unreadable selected fragments. Both forms compose as peers when present. - Operator prompt overrides above embedded catalogs using registered identity; @@ -243,6 +256,11 @@ Validate behavior through the public loading boundary, including: broader containment roots, and missing selected overlays. - Optional discovery exhaustion, required discovery, fallback and skip policies, mixed payload/required-import cases from OD-2, and terminal selected-main errors. +- Unused fallback paths need not exist or be accessible; selected fallback paths + receive normal validation. Inactive overlays ignore fallback settings. +- Empty `path: []` with either requiredness value when no base exists, including + the independent effect of `RequireBase`, and skipped imports without fabricated + completed-search evidence. - Symlinks, eligible namespaces, parent-relative paths within the selected scope, context validity, and namespace identity under OD-3 and OD-4. - Normal source evidence, diagnostics, passive resource contexts, cleanup, and @@ -285,6 +303,16 @@ that complete concrete context wins. Do not merge fields or fall back to derivat when the explicit context is invalid. This permits overriding reusable companion setup without clearing its binding declaration. +An active binding is one selected in the absence of an overriding +`Input.Filesystem`. It applies to non-file underlay inputs, including `Mapping`, +`Bytes`, and `Reader`. An active binding on the main `Input` is an option error +because it would refer to itself. An active binding on a `File`, +`Filesystem.File`, or `SearchConfig` underlay is also an option error: these +sources determine their own file import bases. The concrete-context override +rule still applies before this active-binding scope check. Existing source +behavior is unchanged; express main-relative file acquisition through native +imports in a non-file underlay. + Layered overlays derive automatically when `OverlayFilesystem` is absent; no additional opt-in flag is needed. An explicit overlay context wins as a whole. Support an explicit overlay fallback under OD-2, reusing the small binding @@ -301,9 +329,12 @@ callback, or second file-selection API is needed for this design. Put absence behavior on each derived binding. When no usable base exists, the default skips optional companion import expansion, retaining the declaring -input's ordinary configuration values. Required imports produce an error; -requiredness includes applicable application import defaults. Continue normal -input and directive validation, so absence does not excuse invalid declarations. +input's ordinary configuration values. Imports requiring targets or a nonempty +selection produce an error; requiredness includes applicable application import +defaults. An empty `path: []` still succeeds even with `required: true`, because +there are no named targets to require. `RequireBase` independently requires a +usable context even for that empty declaration. Continue normal input and +directive validation, so absence does not excuse invalid declarations. This preserves independent payload and existing required/optional distinctions without treating the entire input as conditional on main presence. @@ -316,7 +347,15 @@ context in this order: 2. Otherwise, use a usable main-derived context. 3. Otherwise, use the explicitly supplied fallback context, if any. 4. Without any usable context, skip optional imports unless the binding requires - a base. A require-base binding or required import produces an error. + a base. A require-base binding or an import requiring targets or a nonempty + selection produces an error; the empty named-path list remains a no-op. + +Validate static binding declaration shape during preflight. Resolve and check +fallback filesystem locations only if the fallback is selected: an unused +fallback need not exist or be accessible. Preserve existing validation of +supplied concrete contexts. A selected invalid fallback produces its normal +error; lazy fallback checks do not provide recovery from invalid selected input. +When no overlay is selected, ignore its fallback settings. A fallback can satisfy require-base: the option requires a usable context, not an actual main file. Consumers requiring a main file can make discovery required.