eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Load ordinary overlays without a main source

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-24 15:59:39 +00:00
parent 53ce6c63d8
commit 8642337966
10 changed files with 125 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/config.md
View File

@@ -83,9 +83,9 @@ imports, but it has no main declarations to traverse. It accepts an explicit
filesystem context: a host context requires an absolute existing `Root` and may
omit `BaseDir` to use that root as its internal import base; a native context
requires its namespace, `BaseDir`, and `Root`. Supplied context is validated even
when imports are disabled. Active ordinary overlays remain invalid for
`NoSource`. It accepts overrides and remains absent rather than contributing an
empty document.
when imports are disabled. An active ordinary overlay requires this explicit
context. `NoSource` accepts overrides and remains absent rather than contributing
an empty document.
Every source, options, schema, version, defaults, decode, resolution, or validation
failure returns a nil result and a `*LoadError`. Successful results contain caller-owned `Config`, detached
@@ -154,7 +154,8 @@ An active layered overlay requires `LayeredOptions.OverlayFilesystem` explicitly
independent of the main source's namespace. Its name and root-relative lookup
follow the selected-overlay rules below; inactive overlays ignore the context.
The same path in a different filesystem namespace is not a repeated file.
Ordinary `Load` continues to infer its selected-overlay context from its source.
Ordinary `Load` infers overlay context from sources that provide one; with
`NoSource`, it requires the explicit `Options.Filesystem` context.
Source IDs follow acquisition order—main and its depth-first imports, then each
underlay tier's inputs and depth-first imports, then overlay and CLI—even though
@@ -974,6 +975,12 @@ Every other name resolves only to `<configuration-root>/overlays/<name>.yml`, wi
no extension fallback, case normalization, inheritance between overlay files,
or overlay stack. A selected missing overlay is an error.
With `NoSource`, the main input stays absent and the explicit filesystem context
supplies the overlay root. The overlay is recorded as the first acquired source
when no other source exists. Host contexts may use the root-only form described
under [single-source loading](#single-source-loading); native contexts retain
their complete namespace, base, and root requirements.
The overlay is a separately policy-validated YAML mapping. It is loaded after the
base import graph is composed and its schema version is checked, but before defaults
and typed decoding. Overlay bytes, nodes, and source records count toward the same

4
docs/roadmap/implementation.md
View File

@@ -1,6 +1,6 @@
# Configuration Discovery Implementation Plan
Status: in progress. Stages 1, 2, 3, and 4 are complete.
Status: in progress. Stages 1, 2, 3, 4, and 5 are complete.
Implement the target behavior in [the discovery roadmap](discovery.md). That
document owns the selected conventions and OD-1 through OD-5; this plan owns the
@@ -297,7 +297,7 @@ Acceptance: imports can be enabled on absent input without synthetic sources,
while invalid supplied contexts still fail. Run focused load, filesystem,
version, and grouped tests, then the everyday check; mark and commit.
## Stage 5 — Load Ordinary Overlays With An Absent Main
## Stage 5 — Load Ordinary Overlays With An Absent Main (Complete)
1. Replace the ordinary `NoSource` active-overlay rejection with the explicit
context requirement. Resolve absent-input overlay access from its context;