Document and demonstrate native and layered configuration loading

This commit is contained in:
2026-09-29 18:22:45 +00:00
parent 34e18c84c1
commit cbf031aedc
21 changed files with 291 additions and 46 deletions

View File

@@ -161,9 +161,11 @@ Tier precedence is explicit; traversal order within a tier establishes stable
reporting, not permission to override. The distinction and its rationale are
recorded in [ADR 0001](../adr/0001-separate-composition-and-overlay.md).
The main document and its imports currently form the strictly composed base
tier. Input-specific constraints, including CLI path rules and opt-in version
ownership, remain part of the configuration contract. Consistent combination
The main document and its imports form a strictly composed tier. Explicit
underlay groups compose strictly within each group, then combine recursively
from lowest to highest beneath the main tier. Source acquisition kind does not
determine its precedence role. Input-specific constraints, including CLI path
rules and opt-in version ownership, remain part of the configuration contract. Consistent combination
semantics do not require identical acquisition or lifetime behavior from every
source kind.
@@ -172,9 +174,10 @@ parser defaults. Processing order and diagnostics must be deterministic for the
same inputs and options. Invalid input must not produce a successful usable
configuration. Do not run application hooks on invalid typed configuration.
User-controlled precedence is application defaults, composed base, selected
overlay, then explicitly supplied CLI overrides. Applications own flag parsing;
ConfigKit owns overlay semantics and provenance. Domain resolution follows these
User-controlled precedence is application defaults, ordered underlays, composed
main input, selected overlay, then explicitly supplied CLI overrides.
Applications own flag parsing; ConfigKit owns overlay semantics and provenance.
Domain resolution follows these
inputs and must remain recorded, not become a hidden override channel.
Preserve node-based composition until the effective input is ready for typed