base-layer/configkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Clarify binding scope and fallback behavior in the companion roadmap

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-09 18:08:17 +00:00
parent c0bc5e2b73
commit 132b9ec659
1 changed files with 52 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/roadmap/main-relative-inputs.md
View File

@@ -94,10 +94,11 @@ outside this feature; it is not a second spelling for current overlay lookup.
### Companion underlays ### Companion underlays
The application declares an underlay `Input` containing native imports and The application declares a non-file underlay `Input` containing native imports
selects main-derived filesystem binding for that input. `Mapping` and `Bytes` and selects main-derived filesystem binding for that input. `Mapping`, `Bytes`,
are first-class supported sources for this use. OD-1 settles the public API and `Reader` are supported sources for this use. OD-1 settles the public API
structure below; no new operator-facing YAML syntax is needed. 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 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; 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 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 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 optional companion import expansion while retaining the declaring input's
ordinary payload and validation. Required imports still fail. Applications can ordinary payload and validation. Imports requiring targets or a nonempty selection
require a base or supply an explicit fallback context on each derived binding. still fail; an empty `path: []` retains its existing no-op behavior even when
OD-2 records the settled precedence, skip scope, and fallback behavior. 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 Do not infer a directory from unsuccessful candidates or silently use the working
directory. An application may explicitly choose the working directory as its 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. callback, second discovery API, or preliminary full load is required.
Check static declarations during preflight where possible; defer checks requiring 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 diagnostics or filesystem checks. Selected-file and companion acquisition errors
remain terminal rather than restarting discovery. 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 context. Preserve namespace identity, repetition scope, shared budgets, detached
inspection, and acquisition-handle cleanup. 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 Successful existing ordinary and explicitly configured layered loads should retain
their behavior. Automatically deriving a layered overlay context intentionally their behavior. Automatically deriving a layered overlay context intentionally
relaxes the former missing-context error. Companion directory conventions are 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, - Native file mains, bytes/readers/mappings with explicit host or native contexts,
and absent mains with explicit contexts. Cover absent host root-only contexts, and absent mains with explicit contexts. Cover absent host root-only contexts,
missing and invalid contexts, and context reuse without enabling main imports. 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. 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 - File only, directory only, both, neither, empty directories, and invalid or
unreadable selected fragments. Both forms compose as peers when present. unreadable selected fragments. Both forms compose as peers when present.
- Operator prompt overrides above embedded catalogs using registered identity; - 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. broader containment roots, and missing selected overlays.
- Optional discovery exhaustion, required discovery, fallback and skip policies, - Optional discovery exhaustion, required discovery, fallback and skip policies,
mixed payload/required-import cases from OD-2, and terminal selected-main errors. 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, - Symlinks, eligible namespaces, parent-relative paths within the selected scope,
context validity, and namespace identity under OD-3 and OD-4. context validity, and namespace identity under OD-3 and OD-4.
- Normal source evidence, diagnostics, passive resource contexts, cleanup, and - 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 when the explicit context is invalid. This permits overriding reusable companion
setup without clearing its binding declaration. 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 Layered overlays derive automatically when `OverlayFilesystem` is absent; no
additional opt-in flag is needed. An explicit overlay context wins as a whole. 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 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 Put absence behavior on each derived binding. When no usable base exists, the
default skips optional companion import expansion, retaining the declaring default skips optional companion import expansion, retaining the declaring
input's ordinary configuration values. Required imports produce an error; input's ordinary configuration values. Imports requiring targets or a nonempty
requiredness includes applicable application import defaults. Continue normal selection produce an error; requiredness includes applicable application import
input and directive validation, so absence does not excuse invalid declarations. 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 This preserves independent payload and existing required/optional distinctions
without treating the entire input as conditional on main presence. 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. 2. Otherwise, use a usable main-derived context.
3. Otherwise, use the explicitly supplied fallback context, if any. 3. Otherwise, use the explicitly supplied fallback context, if any.
4. Without any usable context, skip optional imports unless the binding requires 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 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. an actual main file. Consumers requiring a main file can make discovery required.