69 lines
3.3 KiB
Markdown
69 lines
3.3 KiB
Markdown
# ADR 0019: Keep Configuration Discovery Explicit and Inside Loading
|
|
|
|
## Status
|
|
|
|
Accepted.
|
|
|
|
## Date
|
|
|
|
2026-10-24
|
|
|
|
## Context
|
|
|
|
Applications often need a small ordered convention for choosing a main
|
|
configuration file. Keeping that choice entirely in each application repeats
|
|
path selection and file-loading plumbing. Moving the convention into ConfigKit
|
|
without an explicit declaration would make ordinary loads search paths that a
|
|
consumer did not choose, obscuring both precedence and filesystem access.
|
|
|
|
ConfigKit already owns synchronous source acquisition, parsing, composition,
|
|
decoding, validation, and inspection. A selected host file can therefore enter
|
|
that lifecycle as the existing file source, preserving its source identity,
|
|
resource context, and diagnostics. Optional exhaustion can use the same absent
|
|
main lifecycle as an explicitly absent source.
|
|
|
|
## Decision
|
|
|
|
Consumers choose and order the main-file conventions they want to use. They may
|
|
describe literal paths, directory filename groups, and supported directory
|
|
presets, and may mark the complete search as required. Search descriptions are
|
|
explicit inputs to loading; no preset or convention is activated implicitly.
|
|
|
|
During synchronous loading, ConfigKit resolves the description to one real host
|
|
file or to absence before parsing. The selected file follows the existing source
|
|
acquisition and processing rules. A selected-file access, parse, version,
|
|
composition, decode, or validation failure is terminal and does not resume the
|
|
search. Optional exhaustion shares the absent-main lifecycle; required
|
|
exhaustion reports a missing-source diagnostic. No candidate-attempt history is
|
|
added to public metadata.
|
|
|
|
This keeps convention choice with applications while moving repeated selection
|
|
and loading plumbing into the library's established lifecycle. It preserves
|
|
explicit control, ordinary source behavior, and complete-on-return ownership.
|
|
|
|
## Alternatives Considered
|
|
|
|
- **Keep all search and fallback loading in each application.** This preserves
|
|
consumer ownership but repeats the file-selection and load coordination that
|
|
ConfigKit already owns, and risks divergent handling of selected-file errors.
|
|
- **Search conventional locations implicitly during every load.** This reduces
|
|
setup, but activates filesystem access and precedence the consumer did not
|
|
select and makes ordinary source behavior less predictable.
|
|
- **Return candidate paths for the application to load one by one.** This keeps
|
|
selection outside the load lifecycle and encourages repeated complete loads,
|
|
potentially rerunning defaults, callbacks, and validation during fallback.
|
|
|
|
## Consequences
|
|
|
|
The public search description must be immutable and root-owned, with private
|
|
engine conversion and selection. The contract documents candidate ordering,
|
|
selection, exhaustion, context, and provenance; the API declaration documents
|
|
the public symbols. Dynamic bases and file availability are observed when each
|
|
load consumes the description. Applications remain responsible for selecting
|
|
conventions and for their schema and domain requirements.
|
|
|
|
The [configuration contract](../config.md) owns implemented behavior, and the
|
|
[component overview](../internal/overview.md) describes implementation ownership.
|
|
The completed implementation plan and remediation record are preserved in Git
|
|
history at `0369111` under `docs/roadmap/`.
|